# Form

Building blocks for forms and settings: labelled fields, sections, rows and messages. Labels can brighten once a value is valid, and row values update in place as they change.

> Composed · Free · Forms & Inputs — React Native, Expo Go compatible.

## Install

```bash
npx @lumioui/cli add form
```

## Import

```tsx
import { useFormContext, useFormField, Form } from "@/components/ui/form/form";
```

## Variants

- `checkout` — Add card: `npx @lumioui/cli add form-checkout`
- `preferences` — Preferences: `npx @lumioui/cli add form-preferences`

## Props

### Form

| Prop | Type | Notes |
| --- | --- | --- |
| `disabled?` | `boolean` | Disable all fields in the form (exposed via useFormContext). |
| `className?` | `string` | — |

### FormField

| Prop | Type | Notes |
| --- | --- | --- |
| `name?` | `string` | Field name (for identification/analytics). |
| `label?` | `string` | Shorthand label — equivalent to rendering <Form.Label>. |
| `required?` | `boolean` | Show a required asterisk on the label. |
| `error?` | `string` | Error message — renders <Form.Message> and marks the field invalid. |
| `description?` | `string` | Hint text shown when there is no error. |
| `valid?` | `boolean` | Opt into the valid light: the label stays muted while false and  switches on to ink when true. Omit to keep the label always ink. |
| `validDelay?` | `number` | Delay before the label's first switch-on, so pre-filled fields light  in reading order (e.g. index × 60). Later changes are immediate. |
| `className?` | `string` | — |
| `labelClassName?` | `string` | — |

### FormLabel

| Prop | Type | Notes |
| --- | --- | --- |
| `className?` | `string` | — |

### FormMessage

| Prop | Type | Notes |
| --- | --- | --- |
| `className?` | `string` | — |

### FormSection

| Prop | Type | Notes |
| --- | --- | --- |
| `title?` | `string` | Optional header text rendered above the group. |
| `footer?` | `string` | Optional footer text rendered below the group. |
| `titleClassName?` | `string` | Extra classes for the header text. |
| `footerClassName?` | `string` | Extra classes for the footer text. |
| `className?` | `string` | — |

### FormRow

| Prop | Type | Notes |
| --- | --- | --- |
| `label` | `string` | Primary label. |
| `description?` | `string` | Secondary description below the label. |
| `leading?` | `React.ReactNode` | Slot rendered before the label (icon, avatar). |
| `trailing?` | `React.ReactNode` | Control rendered on the trailing side (Switch, value text, etc.). |
| `value?` | `string` | Trailing value text ("15 minutes before"). When it changes it swaps in  place — the new value starts dim and ignites. Renders before `trailing`. |
| `showChevron?` | `boolean` | Show a disclosure chevron on the trailing edge. |
| `haptic?` | `"light" | "selection" | false` | Haptic on press. Default "selection"; false to disable. |
| `className?` | `string` | — |
| `labelClassName?` | `string` | — |
| `descriptionClassName?` | `string` | — |
| `children?` | `React.ReactNode` | — |

### FormSeparator

| Prop | Type | Notes |
| --- | --- | --- |
| `className?` | `string` | — |

Source: https://lumioui.com/components/form