fieldset
Groups related form controls together with an optional caption. Essential for organizing complex forms and providing accessible groupings for screen readers.
When to Use
- Grouping related form fields (e.g., billing address, shipping address)
- Radio button or checkbox groups that belong together
- Sections of a multi-part form
- Any time you need to provide a group label for accessibility
Always include a legend as the first child to provide a caption for the group.
Basic Usage
A fieldset with a legend creates a visually and semantically grouped form section.
Basic fieldset with legend
<fieldset> <legend>Contact Information</legend> <layout-stack data-layout-gap="m"> <form-field> <label for="name">Full Name</label> <input type="text" id="name" /> </form-field> <form-field> <label for="email">Email Address</label> <input type="email" id="email" /> </form-field> </layout-stack></fieldset>Style Variants
Default (Bordered)
Standard fieldset with a visible border and legend that breaks the border line.
.minimal
Borderless fieldset for subtle grouping. The legend appears as a heading.
Minimal fieldset
<fieldset class="minimal"> <legend>Notification Preferences</legend> <layout-stack data-layout-gap="s"> <label> <input type="checkbox" name="notify" value="email" /> Email notifications </label> <label> <input type="checkbox" name="notify" value="sms" /> SMS notifications </label> </layout-stack></fieldset>Radio Button Groups
Fieldset is essential for grouping radio buttons. Screen readers will announce the legend before each radio option.
Radio button group in fieldset
<fieldset> <legend>Preferred Contact Method</legend> <layout-stack data-layout-gap="s"> <label> <input type="radio" name="contact-method" value="email" checked /> Email </label> <label> <input type="radio" name="contact-method" value="phone" /> Phone </label> <label> <input type="radio" name="contact-method" value="mail" /> Mail </label> </layout-stack></fieldset>Disabled Fieldset
The disabled attribute on a fieldset disables all form controls within it. VB adds a visual treatment: reduced opacity and desaturation so the entire group appears clearly inactive.
Disabled fieldset
<fieldset disabled> <legend>Disabled Section</legend> <!-- All controls inside are disabled --> <!-- Visual treatment: opacity 0.5 + desaturated --></fieldset>Status Variants
Use data-status to apply a subtle border tint indicating the state of the fieldset's contents. Uses the same vocabulary as inline semantics.
Fieldset status variants
<fieldset data-status="success"> <legend>Payment Complete</legend> <!-- Green-tinted border --></fieldset> <fieldset data-status="warning"> <legend>Verification Needed</legend> <!-- Yellow-tinted border --></fieldset> <fieldset data-status="error"> <legend>Validation Errors</legend> <!-- Red-tinted border --></fieldset>| Value | Border color | Use case |
|---|---|---|
success |
Green-tinted | Validated section, completed step |
warning |
Yellow-tinted | Needs attention, incomplete |
error |
Red-tinted | Validation errors present |
Accessibility Notes
- Always include a legend: The legend provides the accessible name for the group
- Legend must be first child: For proper rendering, legend must be the first element inside fieldset
- Screen reader behavior: The legend is announced before each control in the group
- Required for radio groups: Radio buttons should always be in a fieldset for accessibility
- Avoid nesting too deep: Limit nesting to maintain comprehension
CSS Reference
CSS for fieldset styling
fieldset { border: var(--border-width-thin) solid var(--color-border); border-radius: var(--radius-m); padding: var(--size-m); margin: 0;} /* Minimal/borderless fieldset */fieldset.minimal { border: none; padding: 0;} fieldset.minimal > legend { padding: 0; margin-block-end: var(--size-s); font-size: var(--font-size-md);} /* Disabled visual treatment */fieldset:disabled { opacity: 0.5; filter: saturate(0.3);} fieldset:disabled legend { color: var(--color-text-muted);} /* Status border variants */fieldset[data-status="success"] { border-color: color-mix(in oklab, var(--color-success) 40%, var(--color-border));} fieldset[data-status="warning"] { border-color: color-mix(in oklab, var(--color-warning) 40%, var(--color-border));} fieldset[data-status="error"] { border-color: color-mix(in oklab, var(--color-error) 40%, var(--color-border));} legend { padding-inline: var(--size-s); font-weight: 600; font-size: var(--font-size-sm);}Related
- legend - Caption for the fieldset (required first child)
- form - Container for fieldsets
- input - Form controls within fieldsets
- form-field - Enhanced form field wrapper