Skip to main content

Fieldset

Semantic grouping of related form controls. Fieldset wraps controls that belong together (an address block, a set of checkboxes, a contact details section) and uses <legend> to give the group an accessible name. Built on the native <fieldset> element, the component inherits built-in grouping semantics and the disabled cascade for free.

Usage​

When to use

  • To group related form controls under a single label (e.g. address fields, radio button groups)
  • To disable a whole group of controls at once via the disabled attribute on the fieldset
  • To communicate hierarchy in long or complex forms

When not to use

  • For a single form control - use the control's own label
  • For visual-only grouping unrelated to form semantics - use a plain wrapper or card
  • For attaching elements directly to an input - use addon

Do

  • Provide a <legend> for every fieldset - it becomes the group's accessible name
  • Disable a whole group via the disabled attribute on the fieldset, not on each child
  • Use nested fieldsets only when the group hierarchy is meaningful

Don't

  • Don't omit the <legend> - it is the fieldset's accessible name
  • Don't nest fieldsets purely for visual effect
  • Don't style <legend> to look unrelated to its fieldset

API​

Slots​

SlotRequiredDescription
legend-Visible text for the legend, naming the group for screen readers.
contentYesHTML string of grouped form controls.

Props​

PropTypeDefaultDescription
is_disabledboolean-Renders the disabled attribute, cascading to every contained control.
classesarray-Additional CSS class words merged into the root element.
attributesobject-Additional HTML attributes spread on the root element.

Classes​

ClassCapabilityDefaultDescription
.subtleEmphasis-Lower emphasis; a muted, quieter weight.
.neutralEmphasisYesDefault emphasis; the standard weight at balanced contrast.
.accentEmphasis-Higher emphasis; a stronger, louder weight.
.xsSize-Extra small.
.smSize-Small.
.mdSizeYesMedium.
.lgSize-Large.
.flushSpacing-No separation; the parts meet directly.

Examples​

Default​

Styled <fieldset> with a <legend> wrapping related form controls.

Sibling controls​

A checkbox written as a bare <input> plus the <label> after it, with no wrapper. The two-column grid pairs them, so the group reads the same as one built from the component.

Disabled​

Fieldset with the disabled attribute cascading to every contained control.

Nested​

Nested fieldsets with distinct visual treatment for hierarchy.

Flush​

The flush spacing value drops the border and the inset padding, for a group that only needs its legend.

Accessibility​

  • WCAG 2.2 AA
  • Each fieldset has a <legend> that names the group
  • disabled attribute on the fieldset disables every contained control
  • Nested fieldsets have visually distinct hierarchy
  • Screen readers announce the legend when focus enters any child control