Forms: schema form, inline edit and upload

A form from one definition: its fields with UISet's controls, steps with a review, checks as people type and on submit, and an agent that fills it by field name while a person approves the submit. The same definition is JSON Schema for an agent tool.

Three things forms need that UI SDK leaves to you. SchemaForm draws a whole form from one definition, steps and review included, and the same definition lets an agent fill it. InlineEdit is text you edit where it shows, on UI SDK's createInlineEdit. Upload is a drop zone and a queue of uploads on UI SDK's File input: each file shows its progress and can be canceled, retried or removed. Fields, selects, checkboxes, date and number inputs are UI SDK's own components; see the list.

pnpm dlx shadcn@latest add @uiset/schema-form @uiset/inline-edit @uiset/upload

Parts

PartItemWhat it is
SchemaFormschema-formA form drawn from defineForm: fields, steps, review, submit
defineForm, validateForm, toJSONSchemaschema-formThe definition, its checks, and its fields as JSON Schema
formTool, registerFormToolschema-formThe form as an agent tool, for a model SDK or the browser's agent
InlineEditinline-editA value that turns into a field when you press it
InlineEditRoot, InlineEditPreview, InlineEditInput, InlineEditSave, InlineEditCancel, InlineEditErrorinline-editIts parts, for a layout of your own
UploaduploadA drop zone, a Choose files button and the list of uploads
useUploadQueue, UploadRow, UploadPreviewuploadThe queue as a hook and one file's row, for a layout of your own
createUploadQueueuploadThe queue with no React in it

Schema form

Describe the form once. Its fields draw the form with UISet's controls, check what people type, and become an agent tool's input:

tsx
import { defineForm, SchemaForm, type FormValues } from "@/components/ui/schema-form"

const invite = defineForm({
  name: "invite_teammate", // the tool's name
  title: "Invite a teammate",
  description: "They get an email with a link to join the workspace.",
  fields: {
    email: { kind: "email", label: "Email", required: true },
    role: {
      kind: "choice",
      label: "Role",
      display: "radio",
      default: "editor",
      options: [
        { value: "viewer", label: "Viewer" },
        { value: "editor", label: "Editor" },
      ],
    },
    seats: { kind: "number", label: "Seats", min: 1, max: 50, step: 1, default: 1 },
    notify: { kind: "boolean", label: "Email me when they join", display: "switch" },
  },
  steps: [
    { title: "Who", fields: ["email"] },
    { title: "Access", fields: ["role", "seats", "notify"] },
  ],
})

type Invite = FormValues<typeof invite.fields> // { email: string; role: "viewer" | "editor" | null; … }

<SchemaForm
  form={invite}
  labels={{ submit: "Send invite" }}
  confirm="Sends an invite email to the address given"
  doneMessage="Invite sent."
  onSubmit={async (values) => {
    const response = await sendInvite(values)
    if (response.status === 409) return { email: "They're already in this workspace." }
  }}
/>
  • Kinds: text, email, url, tel, textarea, number, choice (a select, or radios with display: "radio"), boolean (a checkbox, or a switch) and date (an ISO date). Each takes label, description, required, placeholder and default, and the checks its kind has: min and max (length, value or date), step (1 for whole numbers), pattern with patternMessage, and validate(value, values) for a rule of your own.
  • Rules across fields: pass any Standard Schema as schema (zod, valibot, arktype and others implement it). It runs on submit once every field passes; an issue goes under the field its path names, or above the actions.
  • When problems show: leaving a field shows what's wrong with what was typed; an empty required field waits for Next or Submit. Those check the step, or everything, and move focus to the first problem. A field showing a problem is checked again as it changes.
  • Steps: every field is in one step. Next checks the step, and so does Enter in any of its fields; the steps above the form go back to any step done; the last Next shows a review of every value with an Edit per step, and Submit sends. When a step change takes away what had focus (the field you pressed Enter in, Back on the first step, an Edit), focus goes to the new step's first field, or to the submit on the review.
  • onSubmit gets the values. Return problems by field ({ email: "…" }), or under form for the whole form, and they show where they belong, on their step, with focus on the first. A thrown error shows under form. doneMessage is said and shown once it's sent.
  • Controlled or not: value, defaultValue, onValueChange, and step, defaultStep, onStepChange, as every UI SDK component.
  • Words: labels (Next, Back, Submit, the review's words) and the definition's messages translate everything it says.

An agent fills it; a person sends it

The form is one component to an agent, named by its title, with its fields as items and three actions:

ts
await agent.act({
  steps: [{ ref: "Invite a teammate", action: "fill", args: [{ Email: "grace@example.com", role: "Editor", seats: "3" }] }],
})
  • fill takes values by field name or label, as each field takes them: a number from "3", a choice by its value or its label, a switch from "yes". What it can't fill, and what it fills but is wrong, shows under the fields and comes back as the step's error, so the agent can correct it: Seats is at most 50. No field "phone". Its fields: Email, Role, Seats, ….
  • goTo(step) shows a step, checking the steps on the way as Next does; the review is the step after the last. reset starts over.
  • The submit needs a person. The submit button carries data-agent-confirm with confirm (the form's title by default), so an agent's press waits for your bridge's allow to ask, or fails with "Needs a person". confirm={false} lets an agent send it.

The same definition as a tool

formTool(form, agent) is the form as a tool a model calls: its name, a description, the fields as JSON Schema, and execute, which fills the form on the page through your bridge, so allow and the confirmation still apply and the person sees every value land.

ts
import { jsonSchema, tool } from "ai"
import { formTool, registerFormTool } from "@/components/ui/schema-form"

const invite = formTool(inviteForm, agent) // add { submit: "Send invite" } to press it after filling
const tools = { [invite.name]: tool({ description: invite.description, inputSchema: jsonSchema(invite.inputSchema), execute: invite.execute }) }

// Or for the browser's own agent, over WebMCP, beside UI SDK's registerTools:
const unregister = registerFormTool(inviteForm, agent)

toJSONSchema(form) gives the schema alone: required fields, enum for choices (with their labels in the description), format for emails, links and dates, and the limits.

Inline edit

tsx
import { InlineEdit } from "@/components/ui/inline-edit"

const [name, setName] = useState("Atlas")

<h1>
  <InlineEdit
    label="Project name"
    value={name}
    onValueChange={setName}
    validate={(text) => (text.trim() ? null : "A project needs a name.")}
  />
</h1>
  • label is required. It names the group, the field, and the value's button ("Edit Project name: Atlas").
  • value with onValueChange(value, details) controls it, or defaultValue starts it. onValueChange runs once, when an edit is saved, and not at all when the text didn't change. details.reason says how it was saved (enter-key, focus-out, imperative) and details.source is "agent" when an agent did it.
  • validate takes the text and returns what's wrong with it, or nothing. Text that fails stays in the field, which is marked invalid and described by the message; the message is also read out. It clears as soon as the text changes.
  • placeholder ("Empty") shows in place of an empty value.
  • disabled leaves the value readable and reachable by Tab, but it doesn't open.
  • actions adds Save and Cancel buttons beside the field, for touch screens, where there's no Escape key. editLabel, saveLabel and cancelLabel rename the buttons.
  • It takes the type around it, so inside a heading you edit a heading. The value and the field share one box: nothing moves when editing starts. While editing, it takes the width of its row.

The root has data-editing, data-empty, data-invalid and data-disabled to style from.

Upload

Upload doesn't know where files go. You give it upload, a function that sends one file, reports progress and resolves when it's stored. It runs when a file is chosen, dropped or pasted.

tsx
import { Upload, type Uploader } from "@/components/ui/upload"

const upload: Uploader = (file, { signal, onProgress }) =>
  new Promise((resolve, reject) => {
    const request = new XMLHttpRequest()
    request.open("PUT", `/api/files/${encodeURIComponent(file.name)}`)
    request.upload.onprogress = (event) => onProgress(event.loaded / event.total)
    request.onload = () =>
      request.status < 300
        ? resolve(JSON.parse(request.responseText))
        : reject(new Error(`The server said ${request.status}.`))
    request.onerror = () => reject(new Error("The connection dropped."))
    request.onabort = () => reject(new DOMException("Canceled", "AbortError"))
    signal.addEventListener("abort", () => request.abort())
    request.send(file)
  })

<Upload
  label="Attachments"
  hint="Images or PDF, up to 5 MB each"
  accept="image/*,.pdf"
  maxSize={5_000_000}
  upload={upload}
  onUploaded={(file, result) => attach(result)}
/>
  • label is required. It names the upload and its list of files.
  • upload(file, { signal, onProgress }) returns a promise. Call onProgress with how much has gone up, from 0 to 1. signal aborts when the upload is canceled or its file is removed: pass it to fetch, or abort your request on it, as above. What the promise resolves with is the file's result. When it rejects, the error's message is the reason the row shows ("Failed: The connection dropped."), so write it for the person reading it.
  • concurrency (3) is how many files go up at once. The rest wait their turn.
  • accept, maxSize, maxFiles, validate, multiple (on by default), disabled and the rest of File input's props pass through. Files that fail those checks aren't uploaded: each is listed under the drop zone with the reason ("huge.pdf is larger than 5 MB.") until the next change.
  • value with onValueChange(files) controls the files, or defaultValue starts with some. Every file in the list is uploaded, so start with files only if they still need to go up.
  • onUploaded(file, result) and onFailed(file, error) run as each one ends. onItemsChange(items) runs on every change, with each file's status (queued, uploading, done, failed, canceled), progress, error and result.
  • hint is a line under the prompt. labels replaces any of the words shown, and messages what screen readers hear as files finish, for another language.
  • An image shows a small preview; other files show an icon.
  • Removing a file stops its upload. Cancel stops it and keeps the row, ready to retry.

Check uploads on your server too: accept and maxSize are a convenience, not a guard.

A layout of your own

useUploadQueue(files, { upload, concurrency, onUploaded, onFailed }) returns { queue, items }. items is each file's state, and queue has retry(file) and cancel(file). Render UI SDK's File input parts around it, with UploadRow for each file or your own row. Outside React, createUploadQueue(() => options) is the same queue: call start(), then sync(files) whenever the files change, and subscribe(listener) to hear about it.

Keys

KeysWhereDoes
Entera schema form's fieldNext on a step; Submit on the review or a form with no steps
Enter, Space, F2an inline edit's valueStart editing, with the text selected
Enterits fieldSave. Focus goes back to the value
Escapeits fieldPut the text back. Focus goes back to the value
Tabits fieldSave and move on. With text that can't be saved, stay
Up, Down, Home, Endthe list of uploadsMove between files. The list is one tab stop
Delete, Backspacea fileRemove it, which stops its upload
Entera file that failed or was canceledSend it again

A click outside an inline edit saves it, as Tab does. Save and Cancel, and each upload's Cancel, Retry and Remove buttons, are for pointers and touch: they stay out of the Tab order, because the keys above do the same from the field or the row.

For agents

  • InlineEdit is listed by its label, with setValue (saves the text, through validate: text that fails changes nothing), startEditing and cancel. A disabled one has no actions.
  • Upload is a file input listed by its label, with each row's text as its items ("report.pdf 248 kB Uploaded") and clear. An agent can't add files: it has none to give. Each row's Cancel and Retry are buttons named for the file ("Retry report.pdf"), which an agent presses. Each upload's progress bar is listed as "Uploading report.pdf".
  • Removing one file is not something an agent can do yet: UI SDK's bridge doesn't offer the File input's Remove buttons, and its removeFile takes a File (reported as vercel-labs/ui#782). clear removes them all.
  • Neither asks for confirmation.

Web Components

<uiset-schema-form>, <uiset-inline-edit> and <uiset-upload> are in Web Components, on the same primitives and queue. The schema form's element takes the same definition, from @uiset/web:

html
<uiset-schema-form id="invite" confirm="Sends an invite email to the address given" done-message="Invite sent."></uiset-schema-form>
ts
import { defineForm, formTool } from "@uiset/web"

const invite = document.querySelector("uiset-schema-form")! // typed by @uiset/web
invite.labels = { submit: "Send invite" }
invite.send = async (values) => {
  const response = await sendInvite(values)
  if (response.status === 409) return { email: "They're already in this workspace." }
}
invite.form = defineForm({ … }) // as above
invite.addEventListener("valuechange", (e) => save(e.detail.value)) // preventDefault() refuses
  • send is React's onSubmit: what it returns shows. value is live, as a text field's: read it after input, set it to fill the fields (fields left out go to their defaults; setting it fires nothing). Vue's v-model works on it.
  • defaultValue (set it before form), default-step, step, disabled, labels and locale are React's props. heading is the title's level (2, 3 or 4, or false); with false, name it with label. confirm="false" lets an agent send it.
  • It fires valuechange and stepchange. api has fill, goTo, next, back, submit and reset, and agents see the same form React's does. formTool and registerFormTool take the element's form and your bridge.