Fieldset
FreeGroup 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 fieldsetPlayground
Installation
npx wunderui-cli add fieldsetWrites the source into your project with its dependencies and, on first use, the styles - see Installation.
Then import what you need:
import { Fieldset, FieldsetLegend } from "@/components/ui/fieldset"Then use it:
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.
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.
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.
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.
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.
- TaborShift+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 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.
- 1data-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.
- 2data-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.
- 3Optional
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.
- 4
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.
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | (state) => string | undefined | — | Extra classes for the group. Use for the plain surface, or a class to change the 20 px between the children. |
| render | ReactElement | (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. |
| style | CSSProperties | (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.
| Prop | Type | Default | Description |
|---|---|---|---|
| className | string | (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 . |
| render | ReactElement | (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. |
| style | CSSProperties | (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.
get_component("fieldset")npx wunderui-cli add fieldsetThe full library index for assistants is at /llms.txt.