Form

A native form element with consolidated error handling.

Preview

Installation

Install the local ghost-kit source bundle while the registry runs at localhost:3110. It contains this component and its source dependencies. Prepare the local registry first so token dependencies also resolve locally.

Install

npx shadcn@latest add http://localhost:3110/r/ghost-kit.json

Basic usage

123import { Form } from "@/components/ui/form";

<Form onSubmit={(event) => { event.preventDefault(); }}>Form fields</Form>

Structure

Examples

The Preview above is the canonical form example. Compose it with the public parts shown in Structure.

API reference

For inherited behavior and additional part properties, see the Base UI Form API.

Form properties
Prop	Type	Default	Description
`validationMode`	`FormValidationMode`	`'onSubmit'`	Determines when the form should be validated. The `validationMode` prop on `<Field.Root>` takes precedence over this. - `onSubmit` (default): validates the field when the form is submitted, afterwards fields will re-validate on change. - `onBlur`: validates a field when it loses focus. - `onChange`: validates the field on every change to its value.
`errors`	`Errors`		Validation errors returned externally, typically after submission by a server or a form action. This should be an object where keys correspond to the `name` attribute on `<Field.Root>`, and values correspond to error(s) related to that field.
`onFormSubmit`	`((formValues: FormValues, eventDetails: Form.SubmitEventDetails) => void)`		Event handler called when the form is submitted. `preventDefault()` is called on the native submit event when used.
`actionsRef`	`RefObject<FormActions \| null>`		A ref to imperative actions. - `validate`: Validates all fields when called. Optionally pass a field name to validate a single field.
`ref`	`Ref<HTMLFormElement>`		Allows getting a ref to the component instance. Once the component unmounts, React will set `ref.current` to `null` (or call the ref with `null` if you passed a callback ref).
`className`	`string \| ((state: FormState) => string)`		CSS class applied to the element, or a function that returns a class based on the component's state.
`render`	`ReactElement<unknown, string \| JSXElementConstructor<any>> \| ComponentRenderFn<DetailedHTMLProps<FormHTMLAttributes<HTMLFormElement>, HTMLFormElement>, FormState>`		Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render.
`style`	`CSSProperties \| ((state: FormState) => React.CSSProperties)`		Style applied to the element, or a function that returns a style object based on the component's state.