Form

A form wrapper that integrates with Field components for consolidated validation and submission handling. Wraps Base UI's Form primitive with Patch UI styling.

$npx shadcn add @patchui/field

Contact Form

With Custom Validation

Usage

import {
  Form,
  Field,
  FieldLabel,
  FieldDescription,
  FieldError,
  Input,
  Button,
} from "@patchui/react";
 
// Basic form with validation
<Form onFormSubmit={(formValues) => console.log(formValues)}>
  <Field name="email">
    <FieldLabel>Email</FieldLabel>
    <Input type="email" placeholder="you@example.com" required />
    <FieldError />
  </Field>
 
  <Field name="password">
    <FieldLabel>Password</FieldLabel>
    <Input type="password" required />
    <FieldError />
  </Field>
 
  <Button type="submit">Sign In</Button>
</Form>
 
// With custom validation
<Form>
  <Field
    name="username"
    validate={(value) => {
      if (String(value).length < 3) return "Too short.";
      return null;
    }}
    validationMode="onChange"
  >
    <FieldLabel>Username</FieldLabel>
    <Input required />
    <FieldError />
  </Field>
</Form>

Props

Prop	Type	Default	Description
onFormSubmit	(formValues, eventDetails) => void	-	Callback fired when the form is submitted. preventDefault() is called automatically on the native submit event.
validationMode	"onSubmit" \| "onBlur" \| "onChange"	"onSubmit"	Default validation trigger for all fields. Individual Field validationMode props take precedence.
errors	Record<string, string \| string[]>	-	Server-side validation errors. Keys correspond to Field name props, values are error message(s).
actionsRef	RefObject<Form.Actions \| null>	-	Ref to imperative actions. Use actionsRef.current.validate() to programmatically validate all fields or a specific field by name.
className	string	-	Additional CSS classes to apply to the form element.
children	ReactNode	-	Form content - typically Field components with inputs and a submit button.

Notes

Built on HTML forms: Form renders a native <form> element with built-in constraint validation and error consolidation from Base UI.
Field integration: Use name props on Field components to identify fields in onFormSubmit callbacks and errors mapping.
Validation modes: "onSubmit" validates all fields on submit (re-validates on change after first submission). "onBlur" validates on focus loss. "onChange" validates on every input change.
Server errors: Pass server-side validation errors via the errors prop after form submission - they're automatically displayed by FieldError components on the matching fields.
FieldValidity: Use inside a Field to access the raw validity state for custom validation UI beyond the standard FieldError message.