Form

Connect React Hook Form state with accessible labels and validation messages.

View component source ↗

Preview

Example

A minimal example to get started.

Installation

Install this component and its dependencies in a project initialized with shadcn.

pnpm dlx shadcn@latest add https://ui.hyunjoon.net/r/form.json

Usage

This is the basic example. Use the Code tab above for the selected example. Adjust import aliases to match your project.

import { useState } from "react";
import { useForm } from "react-hook-form";

import { Button } from "@/components/ui/button";
import {
  Form,
  FormField,
  FormItem,
  FormLabel,
  FormControl,
  FormDescription,
  FormMessage,
} from "@/components/ui/form";
import { Input } from "@/components/ui/input";

export default function Example() {
  const form = useForm({ defaultValues: { name: "" } });
  const [saved, setSaved] = useState(false);
  return (
    <Form {...form}>
      <form
        className="grid w-full max-w-sm gap-4"
        onSubmit={form.handleSubmit(() => setSaved(true))}
      >
        <FormField
          control={form.control}
          name="name"
          rules={{ required: "Please enter your name." }}
          render={({ field }) => (
            <FormItem>
              <FormLabel>Name</FormLabel>
              <FormControl render={<Input {...field} />} />
              <FormDescription>This is shown to your teammates.</FormDescription>
              <FormMessage />
            </FormItem>
          )}
        />
        <Button type="submit">Save</Button>
        {saved && (
          <p role="status" className="text-sm">
            Profile saved for this preview.
          </p>
        )}
      </form>
    </Form>
  );
}

API reference

Derived from the installed component types. Native DOM props are also supported where applicable. A dash means no explicit default is documented. Some props depend on the selected mode.

Form

Form properties
Prop	Type	Default	Description
`children`Required	React.ReactNode \| React.ReactNode[] React.ReactNode \| React.ReactNode[]	`—`	Content rendered inside this component.
`watch`Required	UseFormWatch<TFieldValues> UseFormWatch<TFieldValues>	`—`	Configures watch; see the accepted type.
`getValues`Required	UseFormGetValues<TFieldValues> UseFormGetValues<TFieldValues>	`—`	Configures get values; see the accepted type.
`getErrors`Required	UseFormGetErrors<TFieldValues> UseFormGetErrors<TFieldValues>	`—`	Configures get errors; see the accepted type.
`getFieldState`Required	UseFormGetFieldState<TFieldValues> UseFormGetFieldState<TFieldValues>	`—`	Configures get field state; see the accepted type.
`setError`Required	UseFormSetError<TFieldValues> UseFormSetError<TFieldValues>	`—`	Configures set error; see the accepted type.
`clearErrors`Required	UseFormClearErrors<TFieldValues> UseFormClearErrors<TFieldValues>	`—`	Configures clear errors; see the accepted type.
`setValue`Required	UseFormSetValue<TFieldValues> UseFormSetValue<TFieldValues>	`—`	Configures set value; see the accepted type.
`setValues`Required	UseFormSetValues<TFieldValues> UseFormSetValues<TFieldValues>	`—`	Configures set values; see the accepted type.
`trigger`Required	UseFormTrigger<TFieldValues> UseFormTrigger<TFieldValues>	`—`	Configures trigger; see the accepted type.
`formState`Required	FormState<TFieldValues> FormState<TFieldValues>	`—`	Configures form state; see the accepted type.
`resetField`Required	UseFormResetField<TFieldValues> UseFormResetField<TFieldValues>	`—`	Configures reset field; see the accepted type.
`reset`Required	UseFormReset<TFieldValues> UseFormReset<TFieldValues>	`—`	Configures reset; see the accepted type.
`resetDefaultValues`Required	UseFormResetDefaultValues<TFieldValues> UseFormResetDefaultValues<TFieldValues>	`—`	Configures reset default values; see the accepted type.
`handleSubmit`Required	UseFormHandleSubmit<TFieldValues, TTransformedValues> UseFormHandleSubmit<TFieldValues, TTransformedValues>	`—`	Configures handle submit; see the accepted type.
`unregister`Required	UseFormUnregister<TFieldValues> UseFormUnregister<TFieldValues>	`—`	Configures unregister; see the accepted type.
`control`Required	Control<TFieldValues, TContext, TTransformedValues> Control<TFieldValues, TContext, TTransformedValues>	`—`	React Hook Form control object for the field.
`register`Required	UseFormRegister<TFieldValues> UseFormRegister<TFieldValues>	`—`	Configures register; see the accepted type.
`setFocus`Required	UseFormSetFocus<TFieldValues> UseFormSetFocus<TFieldValues>	`—`	Configures set focus; see the accepted type.
`subscribe`Required	UseFormSubscribe<TFieldValues> UseFormSubscribe<TFieldValues>	`—`	Configures subscribe; see the accepted type.

FormField

FormField properties
Prop	Type	Default	Description
`render`Required	({ field, fieldState, formState, }: { field: ControllerRenderProps<TValues, TName>; fieldS… ({ field, fieldState, formState, }: { field: ControllerRenderProps<TValues, TName>; fieldState: ControllerFieldState; formState: UseFormStateReturn<TValues>; }) => React.ReactElement	`—`	Element or render function used to compose a custom root element.
`name`Required	TName TName	`—`	Field name used in form data.
`rules`	Omit<RegisterOptions<TValues, TName>, "disabled" \| "valueAsNumber" \| "valueAsDate" \| "setV… Omit<RegisterOptions<TValues, TName>, "disabled" \| "valueAsNumber" \| "valueAsDate" \| "setValueAs"> \| undefined	`—`	Validation rules applied to this field.
`shouldUnregister`	boolean \| undefined boolean \| undefined	`—`	Configures should unregister; see the accepted type.
`defaultValue`	PathValueImpl<TValues, TName> \| undefined PathValueImpl<TValues, TName> \| undefined	`—`	Initial value for an uncontrolled component.
`control`	Control<TValues, any, TValues> \| undefined Control<TValues, any, TValues> \| undefined	`—`	React Hook Form control object for the field.
`disabled`	boolean \| undefined boolean \| undefined	`—`	Prevents user interaction.
`exact`	boolean \| undefined boolean \| undefined	`—`	Configures exact; see the accepted type.

FormItem

FormItem properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLDivElement> \| undefined React.Ref<HTMLDivElement> \| undefined	`—`	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).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLDivElement> \| undefined React.FocusEventHandler<HTMLDivElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLDivElement, Element> \| undefined React.ChangeEventHandler<HTMLDivElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLDivElement> \| undefined React.KeyboardEventHandler<HTMLDivElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLDivElement> \| undefined React.MouseEventHandler<HTMLDivElement> \| undefined	`—`	Called when the element is activated.

FormLabel

FormLabel properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLLabelElement> \| undefined React.Ref<HTMLLabelElement> \| undefined	`—`	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).
`htmlFor`	string \| undefined string \| undefined	`—`	ID of the associated form control.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLLabelElement> \| undefined React.FocusEventHandler<HTMLLabelElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLLabelElement> \| undefined React.FocusEventHandler<HTMLLabelElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLLabelElement, Element> \| undefined React.ChangeEventHandler<HTMLLabelElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLLabelElement> \| undefined React.KeyboardEventHandler<HTMLLabelElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLLabelElement> \| undefined React.MouseEventHandler<HTMLLabelElement> \| undefined	`—`	Called when the element is activated.

FormControl

FormControl properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLInputElement> \| undefined React.Ref<HTMLInputElement> \| undefined	`—`	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).
`alt`	string \| undefined string \| undefined	`—`	Accessible text alternative for the image.
`checked`	boolean \| undefined boolean \| undefined	`—`	Current checked state when controlled.
`disabled`	boolean \| undefined boolean \| undefined	`—`	Prevents user interaction.
`max`	string \| number \| undefined string \| number \| undefined	`—`	Maximum allowed value.
`maxLength`	number \| undefined number \| undefined	`—`	Maximum number of input characters.
`min`	string \| number \| undefined string \| number \| undefined	`—`	Minimum allowed value.
`multiple`	boolean \| undefined boolean \| undefined	`—`	Allows more than one value to be selected.
`name`	string \| undefined string \| undefined	`—`	Field name used in form data.
`placeholder`	string \| undefined string \| undefined	`—`	Hint shown when the control has no value.
`required`	boolean \| undefined boolean \| undefined	`—`	Whether the user must provide a value before form submission.
`src`	string \| undefined string \| undefined	`—`	URL of the displayed resource.
`step`	string \| number \| undefined string \| number \| undefined	`—`	Increment between valid values.
`type`	React.HTMLInputTypeAttribute \| undefined React.HTMLInputTypeAttribute \| undefined	`—`	The native input or button behavior.
`value`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	The current value when controlled by the application.
`onChange`	React.ChangeEventHandler<HTMLInputElement, HTMLInputElement> \| undefined React.ChangeEventHandler<HTMLInputElement, HTMLInputElement> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLInputElement> \| undefined React.FocusEventHandler<HTMLInputElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLInputElement> \| undefined React.FocusEventHandler<HTMLInputElement> \| undefined	`—`	Called when the control loses focus.
`onKeyDown`	React.KeyboardEventHandler<HTMLInputElement> \| undefined React.KeyboardEventHandler<HTMLInputElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLInputElement> \| undefined React.MouseEventHandler<HTMLInputElement> \| undefined	`—`	Called when the element is activated.
`render`	React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn… React.ReactElement<unknown, string \| React.JSXElementConstructor<any>> \| ComponentRenderFn<HTMLProps, {}> \| undefined	`—`	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.

FormDescription

FormDescription properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLParagraphElement> \| undefined React.Ref<HTMLParagraphElement> \| undefined	`—`	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).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLParagraphElement> \| undefined React.FocusEventHandler<HTMLParagraphElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLParagraphElement> \| undefined React.FocusEventHandler<HTMLParagraphElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLParagraphElement, Element> \| undefined React.ChangeEventHandler<HTMLParagraphElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLParagraphElement> \| undefined React.KeyboardEventHandler<HTMLParagraphElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLParagraphElement> \| undefined React.MouseEventHandler<HTMLParagraphElement> \| undefined	`—`	Called when the element is activated.

FormMessage

FormMessage properties
Prop	Type	Default	Description
`ref`	React.Ref<HTMLParagraphElement> \| undefined React.Ref<HTMLParagraphElement> \| undefined	`—`	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).
`defaultChecked`	boolean \| undefined boolean \| undefined	`—`	Initial checked state for an uncontrolled control.
`defaultValue`	string \| number \| readonly string[] \| undefined string \| number \| readonly string[] \| undefined	`—`	Initial value for an uncontrolled component.
`className`	string \| undefined string \| undefined	`—`	Additional CSS classes merged with the component styles.
`id`	string \| undefined string \| undefined	`—`	Unique identifier used to associate labels and descriptions.
`children`	React.ReactNode React.ReactNode	`—`	Content rendered inside this component.
`onFocus`	React.FocusEventHandler<HTMLParagraphElement> \| undefined React.FocusEventHandler<HTMLParagraphElement> \| undefined	`—`	Called when the control receives focus.
`onBlur`	React.FocusEventHandler<HTMLParagraphElement> \| undefined React.FocusEventHandler<HTMLParagraphElement> \| undefined	`—`	Called when the control loses focus.
`onChange`	React.ChangeEventHandler<HTMLParagraphElement, Element> \| undefined React.ChangeEventHandler<HTMLParagraphElement, Element> \| undefined	`—`	Called when the underlying form control changes; inspect the event for its value.
`onKeyDown`	React.KeyboardEventHandler<HTMLParagraphElement> \| undefined React.KeyboardEventHandler<HTMLParagraphElement> \| undefined	`—`	Called when a key is pressed while this element is focused.
`onClick`	React.MouseEventHandler<HTMLParagraphElement> \| undefined React.MouseEventHandler<HTMLParagraphElement> \| undefined	`—`	Called when the element is activated.

Usage notes

Wrap controls in FormField and FormItem. Compose FormControl with render, and pass validation rules to FormField.