# Fieldset

A native fieldset with a legend, for grouping related fields.

- Category: Forms
- Page: https://wunderui.com/components/fieldset
- Tier: Free

## Install

```bash
npx wunderui-cli add fieldset
```

## Import

```tsx
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"
```

## Minimal usage

Then use it:

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"

export function Channels() {
  return (
    <Fieldset>
      <FieldsetLegend>Notification channels</FieldsetLegend>
      <Checkbox label="Email" defaultChecked />
      <Checkbox label="Slack" />
    </Fieldset>
  )
}
```

Expected result: You see a card with the legend Notification channels and two checkbox rows. A screen reader announces the group name when focus enters the first box.

## Usage

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"

export function Example() {
  return (
    <Fieldset aria-describedby="channels-hint">
      <div className="flex flex-col gap-1">
        <div className="flex items-baseline gap-2">
          <FieldsetLegend>Notification channels</FieldsetLegend>
          <span className="text-xs text-text-tertiary in-data-disabled:opacity-40">Required</span>
        </div>
        <p id="channels-hint" className="text-xs text-text-tertiary in-data-disabled:opacity-40">Choose where we send alerts.</p>
      </div>
      <div className="flex flex-col gap-3">
        <Checkbox label="Email" defaultChecked />
        <Checkbox label="Slack" />
        <Checkbox label="Text message" />
      </div>
    </Fieldset>
  )
}
```

## When to use

### Use Fieldset for

- A set of checkboxes that answer one question
- The radios of one choice, or the fields of an address, under one name
- A group that must be switched off or marked invalid as a whole

### Use something else

- [Field](https://wunderui.com/components/field) for one control with its own label, hint and error
- [Card](https://wunderui.com/components/card) for a visual container for unrelated content
- [Radio Group](https://wunderui.com/components/radio-group) for the radio buttons themselves, when you need no legend, hint or error around them
- [Form](https://wunderui.com/components/form) for the form that holds the fieldsets: submit, validation mode and server errors

## Keyboard

A fieldset takes no focus and has no keys of its own. Tab moves through the controls in it as it does anywhere, and a radio group inside it keeps its arrow keys.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous control inside the group. A disabled fieldset takes its fields out of the order. |
| `↑` or `↓` or `←` or `→` | Inside a radio group in the fieldset, moves the choice to the next or previous option. The legend plays no part. |

## Behavior

What the fieldset does itself, and what it leaves to the page.

- **Group semantics:** A native fieldset has the group role, and the legend links to it, so a screen reader says Notification channels, group when focus enters. The legend is a div, so it can sit on a row with a note.
- **Hint and error:** The fieldset sets no description of its own. Give the hint and group error an id and list them on the fieldset, and announce the error or move focus when it appears, since it is not a live region.
- **Invalid:** There is no invalid prop: set the invalid data attribute for a red border and tint. The controls inside decide for themselves, so mark checkboxes, radio groups or Fields invalid too.
- **Disabled:** Disabled dims the legend to 40% and disables every Field inside and all native controls. A Checkbox or Radio Group outside a Field does not read the fieldset, so disable it too.
- **Surface:** The default is a card with a border, 12 px corners and 16 px padding, with 20 px between its children. Remove the border, background and padding with a class name to get the plain group.
- **Motion:** The fieldset has no motion of its own. The controls inside change their colours on the fast duration with the entrance curve.
- **Reduced motion:** Nothing moves, so there is nothing to reduce. The colour changes of the controls stay: they are short fades, not movement.

## Anatomy

- `Fieldset`: The group: a native fieldset with the group role. By default it is a card with a thin border, 12 px corners and 16 px padding, and its legend is the accessible name of the group.
- `FieldsetLegend`: The name of the group in 14 px semibold text. It can sit anywhere inside the fieldset, for example on a row with a note, and it dims with a disabled fieldset.
- `Hint`: A line under the legend in 12 px tertiary text that states the rule. Link it to the fieldset so a screen reader reads it with the group.
- `Controls`: The related controls: checkbox rows, a radio group or fields. Keep 12 px between rows of one kind and 16 px between columns.
- `Legend note`: A word such as Required beside the legend, in 12 px tertiary text. It is for sighted readers, so put the rule itself in the hint where a screen reader hears it.
- `Group error`: One message under the controls that says what to do, with a 14 px alert icon. Link it to the fieldset and mark the fieldset as invalid: the card then takes the red border and tint.

## Best practices

### When to use

- Use a Fieldset when several controls answer one question: a set of checkboxes, the radios of one choice, the fields of an address. One control with its own label needs a Field.

### Do

- Write the legend as the question or the noun of the group, such as Notification channels or Shipping address. It is read before every control, so keep it short.
- State the rule in a hint under the legend and link it to the fieldset. Say it before the person breaks it: Choose where we send alerts.
- Show one error for the group, not one per control, and say what to do: Select at least one option to continue. Show it after the first try to continue, and keep what was chosen.
- Use the plain surface when the group sits straight on the page, and the card when it must stand apart, such as an address block in a long form.
- To switch a group off, disable the Fieldset. For a checkbox or radio group also disable the control, or wrap each in a Field, because only Fields read the Fieldset.

### Don't

- Don't use a Fieldset to draw a box around unrelated content. It names a group for assistive technology; use a Card for a visual container.
- Don't nest a Fieldset in a Fieldset to indent. Nest only when the inner group has a name of its own.
- Don't leave the legend out and put the question in a heading next to the group. The group then has no name for a screen reader.

## API reference

### Fieldset

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the group. Use `border-0 bg-transparent p-0` for the plain surface, or a `gap-*` class to change the 20 px between the children. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.FieldsetHTMLAttributes attributes.

### FieldsetLegend

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | Extra classes for the legend, for example `mb-1`. Put the legend and a note on one row by wrapping both in a `div` with `flex items-baseline gap-2`. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | 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 | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |

Also accepts React.HTMLAttributes attributes.

## Examples

### Content: checkboxes, radios and fields

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"

export function Example() {
  return (
    <Fieldset aria-describedby="channels-hint">
      <div className="flex flex-col gap-1">
        <div className="flex items-baseline gap-2">
          <FieldsetLegend>Notification channels</FieldsetLegend>
          <span className="text-xs text-text-tertiary in-data-disabled:opacity-40">Required</span>
        </div>
        <p id="channels-hint" className="text-xs text-text-tertiary in-data-disabled:opacity-40">Choose where we send alerts.</p>
      </div>
      <div className="flex flex-col gap-3">
        <Checkbox label="Email" defaultChecked />
        <Checkbox label="Slack" />
        <Checkbox label="Text message" />
      </div>
    </Fieldset>
  )
}
```

### Surface: card and plain

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"

export function Example() {
  return (
    <Fieldset aria-describedby="channels-hint">
      <div className="flex flex-col gap-1">
        <div className="flex items-baseline gap-2">
          <FieldsetLegend>Notification channels</FieldsetLegend>
          <span className="text-xs text-text-tertiary in-data-disabled:opacity-40">Required</span>
        </div>
        <p id="channels-hint" className="text-xs text-text-tertiary in-data-disabled:opacity-40">Choose where we send alerts.</p>
      </div>
      <div className="flex flex-col gap-3">
        <Checkbox label="Email" defaultChecked />
        <Checkbox label="Slack" />
        <Checkbox label="Text message" />
      </div>
    </Fieldset>
  )
}
```

### Legend row: legend, hint and required

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"

export function Example() {
  return (
    <Fieldset>
      <FieldsetLegend>Notification channels</FieldsetLegend>
      <div className="flex flex-col gap-3">
        <Checkbox label="Email" defaultChecked />
        <Checkbox label="Slack" />
        <Checkbox label="Text message" />
      </div>
    </Fieldset>
  )
}
```

### States: default, invalid and disabled

```tsx
import { Checkbox } from "@/components/ui/checkbox"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"

export function Example() {
  return (
    <Fieldset aria-describedby="channels-hint">
      <div className="flex flex-col gap-1">
        <div className="flex items-baseline gap-2">
          <FieldsetLegend>Notification channels</FieldsetLegend>
          <span className="text-xs text-text-tertiary in-data-disabled:opacity-40">Required</span>
        </div>
        <p id="channels-hint" className="text-xs text-text-tertiary in-data-disabled:opacity-40">Choose where we send alerts.</p>
      </div>
      <div className="flex flex-col gap-3">
        <Checkbox label="Email" defaultChecked />
        <Checkbox label="Slack" />
        <Checkbox label="Text message" />
      </div>
    </Fieldset>
  )
}
```

## In context

### Shipping address: one switch for the whole group

Tick the box and the fieldset is disabled: legend and fields dim together and leave the tab order. The fields keep their values.

```tsx
import { useState } from "react"
import { Checkbox } from "@/components/ui/checkbox"
import { Field, FieldLabel } from "@/components/ui/field"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"
import { Input } from "@/components/ui/input"

export function Example() {
  const [same, setSame] = useState(false)

  return (
    <div className="flex flex-col gap-4">
      <Checkbox
        label="Ship to my billing address"
        description="Nora Lindgren, Kungsgatan 12, Stockholm."
        checked={same}
        onCheckedChange={setSame}
      />
      <Fieldset disabled={same}>
        <FieldsetLegend>Shipping address</FieldsetLegend>
        <Field>
          <FieldLabel>Street</FieldLabel>
          <Input defaultValue="Kungsgatan 12" autoComplete="address-line1" />
        </Field>
        <div className="grid grid-cols-2 gap-4">
          <Field>
            <FieldLabel>City</FieldLabel>
            <Input defaultValue="Stockholm" autoComplete="address-level2" />
          </Field>
          <Field>
            <FieldLabel>Postal code</FieldLabel>
            <Input defaultValue="11143" inputMode="numeric" autoComplete="postal-code" />
          </Field>
        </div>
      </Fieldset>
    </div>
  )
}
```

### Billing cycle and add-ons: two groups, two legends

Each group has its own legend, so a screen reader says Billing cycle before Monthly and Add-ons before Priority support. Plain groups sit straight on the page.

```tsx
import { useState } from "react"
import { Checkbox } from "@/components/ui/checkbox"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"
import { Label } from "@/components/ui/label"
import { RadioGroup, RadioGroupItem } from "@/components/ui/radio-group"

export function Example() {
  const [cycle, setCycle] = useState("yearly")

  return (
    <div className="flex flex-col gap-6">
      <Fieldset className="gap-3 border-0 bg-transparent p-0">
        <FieldsetLegend>Billing cycle</FieldsetLegend>
        <RadioGroup value={cycle} onValueChange={setCycle}>
          <div className="flex items-center gap-2">
            <RadioGroupItem id="cycle-monthly" value="monthly" />
            <Label htmlFor="cycle-monthly">Monthly</Label>
          </div>
          <div className="flex items-center gap-2">
            <RadioGroupItem id="cycle-yearly" value="yearly" />
            <Label htmlFor="cycle-yearly">Yearly, two months free</Label>
          </div>
        </RadioGroup>
      </Fieldset>
      <Fieldset className="gap-3 border-0 bg-transparent p-0">
        <FieldsetLegend>Add-ons</FieldsetLegend>
        <Checkbox label="Priority support" description="Replies within four business hours." defaultChecked />
        <Checkbox label="Extra seats" description="Five more members for your team." />
      </Fieldset>
    </div>
  )
}
```

### Notification channels: a required group

Press Save channels with nothing chosen. After the first try the card takes the red border and tint, and one message under the group says what to do.

```tsx
import { useState } from "react"
import { CircleAlert } from "lucide-react"
import { Button } from "@/components/ui/button"
import { Checkbox } from "@/components/ui/checkbox"
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"

const CHANNELS = ["Email", "Slack", "Text message"]

export function Example() {
  const [picked, setPicked] = useState<string[]>([])
  const [tried, setTried] = useState(false)
  const [saved, setSaved] = useState(false)
  const invalid = tried && picked.length === 0

  return (
    <div className="flex flex-col gap-4">
      <Fieldset data-invalid={invalid ? "" : undefined} aria-describedby={invalid ? "channels-error" : undefined}>
        <div className="flex items-baseline gap-2">
          <FieldsetLegend>Notification channels</FieldsetLegend>
          <span className="text-xs text-text-tertiary">Required</span>
        </div>
        <div className="flex flex-col gap-3">
          {CHANNELS.map((channel) => (
            <Checkbox
              key={channel}
              label={channel}
              aria-invalid={invalid}
              checked={picked.includes(channel)}
              onCheckedChange={(checked) => setPicked((list) => (checked ? [...list, channel] : list.filter((item) => item !== channel)))}
            />
          ))}
        </div>
        {invalid && (
          <p id="channels-error" className="flex items-center gap-1 text-xs text-text-error">
            <CircleAlert className="size-3.5" aria-hidden />
            Select at least one option to continue.
          </p>
        )}
      </Fieldset>
      <Button
        variant="gradient"
        onClick={() => {
          setTried(true)
          setSaved(picked.length > 0)
        }}
      >
        Save channels
      </Button>
      <p aria-live="polite" className="min-h-5 text-sm text-text-secondary">
        {saved && picked.length > 0 ? `Alerts go to ${picked.join(", ")}.` : ""}
      </p>
    </div>
  )
}
```

## For AI agents

`get_component("fieldset")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
