Fieldset

A fieldset groups FormItems that belong together. It is Headless UI's Fieldset and Legend: the legend names the group through aria-labelledby, the description is wired through aria-describedby, and disabled reaches every Headless UI control inside through context.

import Fieldset from '@zuilib/components/fieldset'

Basic

Loading example

Disabled

disabled on the fieldset disables every FormItem and control inside that has not set its own disabled. Headless UI reads it from context, so this covers Input, Checkbox, Switch, Listbox and the rest.

Loading example

Choice groups

A fieldset without a description is the right wrapper for a set of checkboxes; the legend is what a screen reader announces before each option.

Loading example

Props

FieldsetProps extends Headless UI FieldsetProps (disabled, as, and the <fieldset> attributes) with:

Prop	Type	Default	Description
legend	string	—	Rendered as the <legend>; the group is aria-labelledby it
description	string	—	A <p> under the legend, added to the fieldset aria-describedby
disabled	boolean	false	Inherited by every FormItem and Headless UI control inside
aria-describedby	string	—	Merged with the description id
className	string	—	Merged last onto the fieldset
children	ReactNode	—

Slots

Slot	Element	Notes
[data-slot="fieldset"]	fieldset	Root. Headless UI adds data-disabled
[data-slot="fieldset-legend"]	legend	Present only with legend
[data-slot="fieldset-description"]	p	Present only with description
[data-slot="fieldset-content"]	div	Wraps children; vertical spacing between items

/* Consumer CSS: boxed fieldsets */
[data-slot="fieldset"] {
  padding: calc(var(--spacing) * 4);
  border: 1px solid var(--border);
  border-radius: var(--radius-lg);
}

Tokens

Token	Used for
--foreground	Legend
--muted-foreground	Description
--text-base, --text-sm	Legend and description type
--spacing	Gap between legend, description and items

Accessibility

• Renders a native <fieldset> with a <legend>, so the group name is announced with each control inside.
• description is a plain <p> whose id is merged into the fieldset's aria-describedby (Headless UI's Fieldset provides no description context).
• disabled sets the native attribute and Headless UI's data-disabled; controls inside drop out of the tab order.
• Each FormItem inside is a Headless UI Field that wires its own for / aria-describedby, so no ids are needed.

Related

• FormItem: one field's label, control, description and message.
• Checkbox and Radio Group: the usual group members.
• Label and Description: the parts inside a form item.