Fieldset

Playground

Installation

pnpm add @tessinaui/ui

Usage

import {
  FieldsetRoot,
  FieldsetLegend,
  FieldsetHeader,
  FieldsetDescription,
  FieldsetBody,
  FieldsetHelperText,
} from "@tessinaui/ui";

<FieldsetRoot variant="outline">
  <FieldsetHeader>
    <FieldsetLegend required>Notification preferences</FieldsetLegend>
    <FieldsetDescription>
      Choose how you want to be notified about updates.
    </FieldsetDescription>
  </FieldsetHeader>

  <FieldsetBody>
    <Switch label="Email" defaultChecked />
    <Switch label="SMS" />
    <Switch label="Mobile push" />
  </FieldsetBody>

  <FieldsetHelperText>
    You can change these later in account settings.
  </FieldsetHelperText>
</FieldsetRoot>

Showcase

When to use

Reach for Fieldset when you have a group of related form controls that share a single label, description, or validation message — notification preferences, permission lists, billing options, plan selection, etc. The browser-native <fieldset> it renders gives screen readers the right grouping, and the disabled prop cascades to every form control inside (a behaviour you can't replicate with a <div>).

For a single labeled input, use Field. For a row of toggleable choices, CheckboxGroup and RadioGroup compose naturally inside Fieldset.Body.

API Reference

FieldsetRoot props

FieldsetLegend props

Renders a Base UI Fieldset.Legend (a <div> automatically associated with the fieldset for accessibility).

FieldsetHeader props

A flex column wrapper grouping Legend + Description so they stack with consistent spacing above the body.

FieldsetDescription props

A muted paragraph below the legend. Use it to clarify the purpose of the group.

FieldsetBody props

Lays out children with size-aware gap. Horizontal orientation wraps when content overflows.

FieldsetHelperText props

Notes

• Built on @base-ui/react/fieldset — the disabled prop cascades to descendant form controls via the native <fieldset disabled> behaviour.
• Fieldset.Header is optional. You can place a bare Fieldset.Legend directly in the root if you don't need a description.
• Pair with CheckboxGroup, RadioGroup, or any Field instance for full form composition. Inside Fieldset.Body they inherit the disabled + invalid context naturally.
• invalid={true} is convenience sugar — it sets intent="error" styling without changing the prop on the Root, which keeps the API ergonomic for form libraries that track validation separately.