Fieldset

Base UICopy Anchor Link

Fieldset gives a cluster of controls a visible legend plus optional group-level description and error copy. Use it when Radio or Checkbox options need a shared group name, or when several labeled fields share one section heading.

Pass render to merge the fieldset root with RadioGroup or CheckboxGroup so the group and legend stay one accessible unit. Group validation and name still live on Field.Root above the fieldset; individual options keep their own labels. Border and card chrome belong on Surface, not on Fieldset.

When to useCopy Anchor Link

• A RadioGroup or CheckboxGroup that needs a legend, shared description, or group error
• Several related Textfields under one section name (billing details, address block)

When not to useCopy Anchor Link

• A lone field with its own label (no shared legend)
• Card border, radius, or fill → wrap with Surface
• Immediate settings toggles that do not need a group legend → Switch rows alone

RelatedCopy Anchor Link

• Radio — mutually exclusive options inside Fieldset
• Checkbox — multi-select options inside Fieldset
• Surface — border and card chrome around the group

Common examplesCopy Anchor Link

Labeled sectionCopy Anchor Link

A Surface card with a Fieldset legend over related Textfields is the baseline field grouping — no render merge when children already own their labels.

Nested RadioGroupCopy Anchor Link

Choice groups that need a shared legend or description merge RadioGroup through render under Field.Root. Each option keeps its own label / description.

Group errorCopy Anchor Link

Drive Fieldset error from Field.Root invalid. Keep description set — helper copy shows while valid; error replaces it when invalid. Surface owns the card chrome; highlight checked cards with color.

Ask your agentCopy Anchor Link

Build a billing details card with a Fieldset legend and two fields: Company and Tax ID. Put a horizontal separator under the legend.