Fieldset

Summary

Fieldset groups related controls under one semantic boundary. It exposes FieldsetLegend and FieldsetHeader so grouped form sections can keep both native <fieldset> semantics and VegaUI layout structure, instead of relying on purely visual containers.

Imports

import {
  Fieldset,
  FieldsetHeader,
  FieldsetLegend,
  type FieldsetAppearance,
  type FieldsetHeaderProps,
  type FieldsetLegendProps,
  type FieldsetProps,
} from '@vega-ui/react';

Exported Types

• FieldsetProps
• FieldsetLegendProps
• FieldsetHeaderProps
• FieldsetAppearance = 'transparent' | 'outlined' | string

Minimal Composition

import {
  Checkbox,
  CheckboxCheckedIcon,
  CheckboxIndicator,
  CheckboxInput,
  Fieldset,
  FieldsetHeader,
  FieldsetLegend,
  Text,
} from '@vega-ui/react';
import { useId } from 'react';

Required Parts

• Fieldset: semantic group boundary and layout container
• FieldsetLegend: primary group label for assistive technology

Optional Parts

• FieldsetHeader: extra header copy between the legend and grouped controls

Composition Order

1. Fieldset
2. FieldsetLegend
3. FieldsetHeader
4. grouped controls

Variants

• Appearance: outlined or transparent
• Content density: legend only or legend plus header copy
• Composition: plain semantic grouping or richer settings section layout

Edge Cases

• FieldsetLegend should stay the first meaningful label inside the group.
• transparent keeps semantics but removes visual framing, which makes surrounding layout responsible for separation.
• Nested fieldsets are valid, but the legend hierarchy must stay obvious.
• Group-level helper or error copy should read as belonging to the whole control group, not to one individual control by accident.

Common Mistakes

• Replacing FieldsetLegend with plain text and losing group semantics.
• Using FieldsetHeader as the only label for the group.
• Using transparent when the section no longer reads as a distinct form group.

Examples

Basic

Basic: notification channels

FieldsetLegend is the first child, so it names the group, and screen readers announce "Payment failure alerts" before each checkbox. The description in FieldsetHeader is linked to the group with aria-describedby.

import {
  Checkbox,
  CheckboxCheckedIcon,
  CheckboxIndicator,
  CheckboxInput,
  Fieldset,
  FieldsetHeader,
  FieldsetLegend,
  Text,
} from '@vega-ui/react';
import { useId } from 'react';

Controlled/Stateful

Controlled/Stateful: choice reveals a dependent group

A radio group in a transparent fieldset holds the delivery method in state, and the matching address or pickup group renders below it. Each dependent group has its own legend.

import {
  Fieldset,
  FieldsetLegend,
  Label,
  Radio,
  TextField,
  TextFieldInput,
} from '@vega-ui/react';
import { useId, useState } from 'react';

type Method = 'courier' | 'pickup';

Form/Integration

Form/Integration: settings form in sections

Several outlined fieldsets split one form into named sections. FormData reads every field across all sections on submit, and reset restores the defaults.

import {
  Button,
  Checkbox,
  CheckboxCheckedIcon,
  CheckboxIndicator,
  CheckboxInput,
  Fieldset,
  FieldsetLegend,
  Label,
  Text,
  TextField,
  TextFieldInput,

Layout/Overlay

Layout/Overlay: transparent group in a dialog

The dialog already draws the container, so appearance='transparent' keeps the group semantics without a second border. Each switch is named by its own Label.

import type { CSSProperties } from 'react';
import {
  Button,
  Dialog,
  DialogClose,
  DialogContent,
  DialogTrigger,
  Fieldset,
  FieldsetLegend,
  Heading,
  Icon,
  IconButton,

Error

Error: at least one option required

The rule belongs to the group, not to one checkbox, so the message sits right after the legend and the fieldset references it with aria-describedby. It appears on submit and clears as soon as one channel is checked. aria-invalid is not valid on a group, so it is not used.

import {
  Button,
  Checkbox,
  CheckboxCheckedIcon,
  CheckboxIndicator,
  CheckboxInput,
  Fieldset,
  FieldsetLegend,
  HelperText,
} from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';

Disabled

Disabled: inherited by every control

disabled on Fieldset disables every descendant control at once — text fields, number steppers and buttons — without passing props to each. Disabled fields are left out of FormData; submit to see which fields arrive.

import {
  Button,
  Fieldset,
  FieldsetLegend,
  Label,
  NumberField,
  NumberFieldDecrementButton,
  NumberFieldIncrementButton,
  NumberFieldInput,
  Switch,
  SwitchIndicator,
  SwitchInput,

Edge

Edge: nested groups

An inner fieldset with its own legend names a sub-question inside a larger section; screen readers announce both legends. Nest only when the scopes are clearly different.

import {
  Fieldset,
  FieldsetLegend,
  Label,
  Radio,
  TextField,
  TextFieldInput,
} from '@vega-ui/react';
import { useId } from 'react';

const WINDOWS = [
  { value: 'morning', label: 'Morning, 8:00–12:00' },

Anatomy

Overview

Fieldset is a small compound component. The root provides native group semantics, FieldsetLegend names the group, and FieldsetHeader adds optional supporting copy.

Required Parts

Fieldset

Required. Renders the <fieldset> element and owns visual appearance.

FieldsetLegend

Required for accessible group labeling. Renders the group name in the native legend slot.

Optional Parts

FieldsetHeader

Optional descriptive block placed after the legend. Use it for supporting copy, not as a replacement for the legend.

Composition Order

1. Fieldset
2. FieldsetLegend
3. FieldsetHeader
4. grouped controls

Valid Composition Patterns

import {
  Checkbox,
  CheckboxCheckedIcon,
  CheckboxIndicator,
  CheckboxInput,
  Fieldset,
  FieldsetHeader,
  FieldsetLegend,
  Text,
} from '@vega-ui/react';
import { useId } from 'react';

Invalid Composition Patterns

Missing FieldsetLegend

The controls remain grouped visually, but the semantic group label disappears.

Decorative heading outside the root used as the only label

This looks correct visually but does not provide native legend semantics.

Deeply nested groups without clear copy

Nested fieldsets become hard to understand when legends do not establish a clear hierarchy.