Form

Form

Markdown

A native form wrapper that consolidates Field values, validation, and submission handling.

Use Form when multiple Field components should share validation timing, server errors, and a structured submit callback.

We will send a confirmation message.

Validated form

Installation

$npx shadcn@latest add @patchui/field

Form is installed with Field from the field registry JSON. The canonical implementation lives in packages/react/src/components/field.tsx.

Usage

<Form onFormSubmit={(values) => save(values)}>
  <Field name="email">
    <FieldLabel>Email</FieldLabel>
    <Input type="email" required />
    <FieldError />
  </Field>
  <Button type="submit">Save</Button>
</Form>

onFormSubmit receives consolidated values keyed by each Field name. When supplied, it prevents the native submit event automatically.

Composition

Form
├── Field
│   ├── FieldLabel
│   ├── control
│   └── FieldError
└── submit Button

Examples

Server errors

Pass external validation errors by Field name. Matching FieldError components display those messages without duplicating server state inside each field.

That email address is already registered.
Server errors

API reference

PropTypeDefaultDescription
onFormSubmit(formValues, eventDetails) => void-Receives consolidated field values after successful validation.
validationMode"onSubmit" | "onBlur" | "onChange""onSubmit"Sets the default validation trigger for fields in the form.
errorsRecord<string, string | string[]>-Maps external errors to matching Field names.
actionsRefRefObject<Form.Actions | null>-Exposes validate() for the complete form or one named field.

A Field-level validationMode overrides the Form default. In onSubmit mode, invalid fields revalidate on change after the first submission attempt.

Accessibility

  • Form renders a native form element and preserves browser submission and constraint-validation semantics.
  • Give every Field a visible label and a stable name that matches submitted values and external errors.
  • Keep FieldError adjacent to its control so validation messages participate in the Field relationship.
  • Move focus to the first invalid field after a failed submission when application flow does not already do so.
  • Announce asynchronous submission success or failure in an appropriate live region.