Skip to content
Nexus Application Design nadesign

Fieldset

<Fieldset> is a styled <fieldset> + <legend>. Use to group related form fields semantically — the native elements expose group structure to assistive tech that wrapping <div>s don’t.

import from "@na/ui/components/Fieldset" ▶ Open in Storybook packages/ui/src/components/Fieldset.tsx

When to use

  • A run of related toggles or fields under a single legend (“Notifications”, “Beta features”).
  • Sub-groups inside a FormSection that warrant their own border + legend.

Don’t use Fieldset for: top-level form sections (use FormSection — heading + spacing, no border), or single-field groups (the <Label> is already the semantic group).

Default

Notifications

When and how you hear from us.

 
<Fieldset legend="Notifications" description="When and how you hear from us.">
  <Label className="flex items-center gap-3">
    <Switch defaultChecked /> Email digest
  </Label>
  <Label className="flex items-center gap-3">
    <Switch /> Slack alerts
  </Label>
</Fieldset>

Disabled

Sets the native disabled on <fieldset> — propagates to every form control inside, no per-field disabled needed.

Beta features (admin only)
 
<Fieldset legend="Beta features (admin only)" disabled>…</Fieldset>

API

Prop Type Default Description
legend * ReactNode — Visible legend. Required for accessibility.
description ReactNode — Optional muted helper paragraph below the legend.
disabled boolean false Native disabled — disables every form control inside.
...rest FieldsetHTMLAttributes — All native fieldset attributes are forwarded.

Design guidelines

✓ Do

  • Use Fieldset whenever 2+ related fields share a meaning. The native semantic helps screen-reader users immensely.
  • Keep the legend short — one noun phrase. Description carries the explanation.

✗ Don't

  • Use Fieldset for visual grouping only. If the group has no semantic name, you don't need a fieldset.
  • Nest Fieldsets more than one level deep. The visual hierarchy collapses.

Accessibility

  • Native <fieldset> + <legend> semantics — assistive tech announces the legend before each field inside.
  • Native disabled propagates to nested form controls automatically — no per-field disabled needed.
  • FormSection — Heading + spacing only, no border.
  • Form — react-hook-form integration.

▶ Open Fieldset stories in Storybook