Skip to content
WunderUI

Fieldset

Free

Group related controls under one legend, so a screen reader names the group first and the group can carry one hint, one error and one disabled state.

npx wunderui-cli add fieldset

Playground

Notification channels
Required

Choose where we send alerts.

Installation

bash
npx wunderui-cli add fieldset

Writes the source into your project with its dependencies and, on first use, the styles - see Installation.

Then import what you need:

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

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.

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 for

  • Field for one control with its own label, hint and error
  • Card for a visual container for unrelated content
  • Radio Group for the radio buttons themselves, when you need no legend, hint or error around them
  • Form for the form that holds the fieldsets: submit, validation mode and server errors

Content

A fieldset holds anything that belongs under one name: a set of checkboxes, one choice out of several radios, or the fields of an address.

Notification channels
Required

Choose where we send alerts.

Surface

By default a fieldset is a card with a 1 px border, a 12 px corner and 16 px of padding. Remove the border, background and padding for the plain group of the Figma set.

Notification channels
Required

Choose where we send alerts.

Legend row

The legend names the group and a hint under it states the rule. A note like Required on the legend row says whether the group may be skipped.

Notification channels

States

An invalid fieldset takes the red border and tint, with one message under it saying what to do. Disabled dims the legend and switches off the fields inside.

Notification channels
Required

Choose where we send alerts.

Keyboard interactions

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.

TaborShiftTab
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 and motion

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 is a native fieldset with a legend. It names a group of related controls and can carry one hint, one error and one disabled state for all of them.

Notification channels

Choose where we send alerts.

  • data-slot="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.

  • data-slot="fieldset-legend"

    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.

  • Optional

    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.

  • The related controls: checkbox rows, a radio group or fields. Keep 12 px between rows of one kind and 16 px between columns.

  • Optional

    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.

  • Optional

    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

  • 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.

  • Do

    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.

  • Do

    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.

  • Do

    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.

  • Do

    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

    Don't nest a Fieldset in a Fieldset to indent. Nest only when the inner group has a name of its own.

  • Don’t

    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 renders a native fieldset and takes every attribute of it, plus a ref. FieldsetLegend renders a div, and the tables list the props of the Base UI parts.

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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the group. Use for the plain surface, or a class to change the 20 px between the children.
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.
styleCSSProperties | (state) => CSSProperties | undefined—Style applied to the element, or a function that returns a style object based on the component's state.

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.

PropTypeDefaultDescription
classNamestring | (state) => string | undefined—Extra classes for the legend, for example . Put the legend and a note on one row by wrapping both in a with .
renderReactElement | (props, state) => ReactElement—Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a or a function that returns the element to render.
styleCSSProperties | (state) => CSSProperties | undefined—Style applied to the element, or a function that returns a style object based on the component's state.

Notes for AI

Give your coding assistant the Markdown reference instead of screenshots.

MCPget_component("fieldset")
Installnpx wunderui-cli add fieldset

The full library index for assistants is at /llms.txt.