# Form (react-hook-form)

Validated form composition built on react-hook-form. `<FormField>` wires a controller into descendant `<FormLabel>` / `<FormControl>` / `<FormDescription>` / `<FormMessage>` parts via shared aria attributes — labels point to inputs, errors are announced, and focus rings show on the right element automatically.

[View examples](https://marsam.rahhal.app/components/form) · [Agent index](https://marsam.rahhal.app/llms.txt)

**Import:** `@rahhal/ui/form`

**Category:** `forms`

## Pieces

| part | role |
| --- | --- |
| Form | re-export of react-hook-form's `<FormProvider>`; spread `useForm()` methods into it |
| FormField | Controller wrapper that exposes `name` to descendants |
| FormItem | vertical stack for one field group |
| FormLabel | themed label — turns destructive on validation error |
| FormControl | Slot that wires `id` / `aria-describedby` / `aria-invalid` onto the input |
| FormDescription | subdued helper text below the control |
| FormMessage | renders the field's validation error (or any children if no error) |
| useFormField() | hook for advanced custom parts |

## Pattern

```tsx
const form = useForm<Values>({ defaultValues: { email: "" } });

<Form {...form}>
  <form onSubmit={form.handleSubmit(onSubmit)}>
    <FormField
      name="email"
      control={form.control}
      rules={{ required: "Required" }}
      render={({ field }) => (
        <FormItem>
          <FormLabel>Email</FormLabel>
          <FormControl><Input {...field} /></FormControl>
          <FormMessage />
        </FormItem>
      )}
    />
  </form>
</Form>
```

## Notes

- The package treats `react-hook-form` as an **optional peer dependency** — add it to apps that use `<Form>`. Apps that don't won't pull it in.
- For schema-based validation, plug `@hookform/resolvers/zod` (or yup) into `useForm({ resolver })`. The components don't care which validator runs.