# Field

A layout primitive for form fields — label, description, and inputs.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="field" title="field.tsx" previewClassName="h-auto py-8">
<FieldDemo />
</ComponentPreview>

Field wraps a form control with its label, description, and error message. It handles vertical and horizontal orientation, works with `FieldSet` and `FieldGroup` for multi-field forms, and surfaces validation state through `data-invalid` on the wrapper.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add field
```

The CLI installs the registry dependencies: `label` and `separator`.
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="field" title="components/ui/field.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="field.tsx"
import { Field, FieldDescription, FieldLabel } from "@/components/ui/field";
import { Input } from "@/components/ui/input";
<DocsBaseSwitcher base="web" component="field" className="mb-6" />
```

```tsx
<Field>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" type="email" placeholder="name@example.com" />
  <FieldDescription>We'll send updates to this address.</FieldDescription>
</Field>
```

## Composition [#composition]

```text
Field
├── FieldLabel
├── FieldDescription
├── FieldError
└── FieldContent
```

## Examples [#examples]

### Input [#input]

<ComponentPreview name="field-input" title="field-input.tsx" src="examples/field-input.tsx" previewClassName="h-auto py-8">
<FieldInput />
</ComponentPreview>

```tsx
<FieldSet>
  <FieldGroup>
    <Field>
      <FieldLabel htmlFor="username">Username</FieldLabel>
      <Input id="username" placeholder="Max Leiter" />
      <FieldDescription>
        Choose a unique username for your account.
      </FieldDescription>
    </Field>
    <Field>
      <FieldLabel htmlFor="password">Password</FieldLabel>
      <FieldDescription>Must be at least 8 characters.</FieldDescription>
      <Input id="password" type="password" />
    </Field>
  </FieldGroup>
</FieldSet>
```

### Textarea [#textarea]

<ComponentPreview name="field-textarea" title="field-textarea.tsx" src="examples/field-textarea.tsx" previewClassName="h-auto py-8">
<FieldTextarea />
</ComponentPreview>

```tsx
<Field>
  <FieldLabel htmlFor="feedback">Feedback</FieldLabel>
  <Textarea id="feedback" rows={4} />
  <FieldDescription>Share your thoughts.</FieldDescription>
</Field>
```

### Invalid [#invalid]

Set `data-invalid` on **Field** (or `aria-invalid` on the control) to trigger destructive styling on the label and control ring.

<ComponentPreview name="field-invalid" title="field-invalid.tsx" src="examples/field-invalid.tsx" previewClassName="h-auto py-8">
<FieldInvalid />
</ComponentPreview>

```tsx
<Field data-invalid>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" aria-invalid />
  <FieldDescription>This field contains validation errors.</FieldDescription>
</Field>
```

### With FieldError [#with-fielderror]

```tsx
<Field data-invalid>
  <FieldLabel htmlFor="email">Email</FieldLabel>
  <Input id="email" aria-invalid />
  <FieldError>Email is required.</FieldError>
</Field>
```

### Horizontal with FieldContent [#horizontal-with-fieldcontent]

`orientation="horizontal"` places the label and control side by side. Use **FieldContent** to stack a title and description beside the control.

```tsx
<Field orientation="horizontal">
  <Checkbox id="terms" />
  <FieldLabel htmlFor="terms">Accept terms and conditions</FieldLabel>
</Field>
```

```tsx
<Field orientation="horizontal">
  <FieldContent>
    <FieldTitle>Share across devices</FieldTitle>
    <FieldDescription>Focused settings sync between devices.</FieldDescription>
  </FieldContent>
  <Switch id="sync" />
</Field>
```

### Separator with label [#separator-with-label]

```tsx
<FieldSeparator>Or continue with</FieldSeparator>
```

### Checkbox in horizontal Field [#checkbox-in-horizontal-field]

Combine `orientation="horizontal"` with `Checkbox` and `FieldLabel` for an inline consent row.

<ComponentPreview name="field-checkbox" title="field-checkbox.tsx" src="examples/field-checkbox.tsx" previewClassName="h-auto py-8">
<FieldCheckbox />
</ComponentPreview>

```tsx
<Field orientation="horizontal">
  <Checkbox id="terms" />
  <FieldLabel htmlFor="terms">Accept terms and conditions</FieldLabel>
</Field>
```

### Switch with FieldContent [#switch-with-fieldcontent]

Use `FieldContent` to stack a `FieldTitle` and `FieldDescription` beside the `Switch`.

<ComponentPreview name="field-switch" title="field-switch.tsx" src="examples/field-switch.tsx" previewClassName="h-auto py-8">
<FieldSwitch />
</ComponentPreview>

```tsx
<Field orientation="horizontal">
  <FieldContent>
    <FieldTitle>Share across devices</FieldTitle>
    <FieldDescription>Focused settings sync between devices.</FieldDescription>
  </FieldContent>
  <Switch id="sync" />
</Field>
```

### Select [#select]

Compose `Field` with `Select` for a labelled dropdown with a description.

<ComponentPreview name="field-select" title="field-select.tsx" src="examples/field-select.tsx" previewClassName="h-auto py-8">
<FieldSelect />
</ComponentPreview>

```tsx
<Field>
  <FieldLabel htmlFor="fruit">Favorite fruit</FieldLabel>
  <Select>
    <SelectTrigger id="fruit">
      <SelectValue placeholder="Select a fruit" />
    </SelectTrigger>
    <SelectContent>
      <SelectItem value="apple">Apple</SelectItem>
      <SelectItem value="banana">Banana</SelectItem>
      <SelectItem value="cherry">Cherry</SelectItem>
    </SelectContent>
  </Select>
  <FieldDescription>Choose one from the list.</FieldDescription>
</Field>
```

## In Context [#in-context]

### Login form [#login-form]

<ComponentPreview name="field-login" title="field-login.tsx" src="examples/field-login.tsx">
<FieldLogin />
</ComponentPreview>

## API Reference [#api-reference]

### Field [#field]

<PropsTable rows={[{"name":"orientation","type":"\"vertical\" | \"horizontal\"","defaultValue":"\"vertical\"","description":"Stack label above the control, or place it beside the control."},{"name":"data-invalid","type":"boolean","defaultValue":"false","description":"Propagates invalid styling to the label and any descendant with data-slot=input."},{"name":"data-disabled","type":"boolean","defaultValue":"false","description":"Grays out label and description."}]} />

### FieldSet / FieldLegend / FieldGroup / FieldLabel / FieldDescription / FieldContent / FieldTitle [#fieldset--fieldlegend--fieldgroup--fieldlabel--fielddescription--fieldcontent--fieldtitle]

Extend native `<fieldset>`, `<legend>`, `<div>`, `<label>`, and `<p>`.

### FieldError [#fielderror]

<PropsTable rows={[{"name":"children","type":"ReactNode","defaultValue":"","description":"Single error message to render."},{"name":"errors","type":"Array<{ message?: string } | undefined>","defaultValue":"","description":"Array of field errors; renders unique messages joined. Children take priority."}]} />

### FieldSeparator [#fieldseparator]

Renders Frakment `Separator`. Accepts an optional `children` that renders as a centered label between two divider lines.

## CSS Variables [#css-variables]

| Variable | Default | Purpose |
| :-- | :-- | :-- |
| `--field-gap` | theme spacing | Gap between label, control, description |

## States [#states]

| State | How |
| :-- | :-- |
| Default | — |
| Invalid | `data-invalid="true"` on `Field` |
| Disabled | `data-disabled="true"` |

## Data Attributes [#data-attributes]

| Attribute | Values |
| :-- | :-- |
| `data-slot` | `field-set`, `field-group`, `field`, `field-label`, `field-description`, `field-error`, `field-content` |
| `data-invalid` | `true` |
| `data-disabled` | `true` |
| `data-orientation` | `vertical` \| `horizontal` |

## Accessibility [#accessibility]

- `Field` does not add roles. It is a layout primitive that groups `FieldLabel` with its control.
- Use `htmlFor` on `FieldLabel` and `id` on the control.
- `FieldError` is linked automatically when the parent `Field` has `data-invalid`.

## Best Practices [#best-practices]

- **One Field per control.** Do not nest fields.
- **Use `FieldGroup` for multiple fields.** It normalizes vertical spacing.
- **Horizontal orientation works for Checkbox and Switch.** Not for inputs.
- **Pair label with description, not placeholder.** Placeholders disappear.
## Related Components [#related-components]

- [Input](/docs/components/web/input) — single-line text
- [Label](/docs/components/web/label) — plain label
- [Checkbox](/docs/components/web/checkbox) — boolean field