# Fieldset Guides
## Patterns
### Settings Section
When to use:
- a settings screen contains several related toggles
- the group should read as one preference area
Composition notes:
- keep `FieldsetLegend` short and stable
- use `FieldsetHeader` for extra guidance
- render the actual toggles directly after the header
Trade-offs:
- improves semantic grouping and scanability
- adds more vertical structure than a loose list of controls
```tsx
import {
Checkbox,
CheckboxCheckedIcon,
CheckboxIndicator,
CheckboxInput,
Fieldset,
FieldsetHeader,
FieldsetLegend,
Text,
} from '@vega-ui/react';
import { useId } from 'react';
const CHANNELS = [
{ value: 'email', label: 'Email', checked: true },
{ value: 'slack', label: 'Slack #billing-alerts', checked: true },
{ value: 'sms', label: 'SMS to the account owner', checked: false },
];
export default function NotificationChannels() {
const id = useId();
return (
);
}
```
### Transparent Group In Existing Panel
When to use:
- the parent layout already provides the visible container
- only the grouping semantics are missing
Composition notes:
- switch to `appearance='transparent'`
- keep the legend even when border and padding are removed
Trade-offs:
- preserves semantics without duplicating containers
- makes the group boundary depend on surrounding layout
```tsx
import type { CSSProperties } from 'react';
import {
Button,
Dialog,
DialogClose,
DialogContent,
DialogTrigger,
Fieldset,
FieldsetLegend,
Heading,
Icon,
IconButton,
Label,
Switch,
SwitchIndicator,
SwitchInput,
} from '@vega-ui/react';
import { XIcon } from '@vega-ui/icons';
import { useId } from 'react';
const SETTINGS = [
{ name: 'showEmail', label: 'Show my email to teammates', checked: true },
{ name: 'showActivity', label: 'Show when I was last active', checked: false },
{ name: 'searchable', label: 'Let people find me by phone number', checked: false },
];
const rowStyle = { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: 'var(--spacing-8)' };
export default function PrivacySettingsInDialog() {
const id = useId();
return (
);
}
```
### Grouped Validation Copy
When to use:
- several related controls fail one business rule
- the error belongs to the group rather than a single input
Composition notes:
- keep the legend as the stable group name
- place the message right after the legend and reference it from the fieldset with `aria-describedby`
- let child controls still render their own local state if needed
Trade-offs:
- clarifies group-level validation
- can become noisy if every child control also repeats the same message
```tsx
import {
Button,
Checkbox,
CheckboxCheckedIcon,
CheckboxIndicator,
CheckboxInput,
Fieldset,
FieldsetLegend,
HelperText,
} from '@vega-ui/react';
import { FormEvent, useId, useState } from 'react';
const CHANNELS = ['Email', 'Push', 'SMS'];
export default function AtLeastOneChannel() {
const id = useId();
const [selected, setSelected] = useState([]);
const [submitted, setSubmitted] = useState(false);
const invalid = submitted && selected.length === 0;
const toggle = (channel: string) => {
if (selected.includes(channel)) {
setSelected(selected.filter((item) => item !== channel));
return;
}
setSelected([...selected, channel]);
};
const onSubmit = (event: FormEvent) => {
event.preventDefault();
setSubmitted(true);
};
return (
);
}
```
### Header With Action
When to use:
- the group has an action that affects all of its fields, such as autofill or reset
Composition notes:
- keep `FieldsetLegend` the first child, so it names the group
- put the helper copy and the `Button` in `FieldsetHeader`, with `type='button'` so it does not submit the form
Trade-offs:
- the action sits next to the fields it changes
- a disabled fieldset disables the action too
```tsx
import {
Button,
Fieldset,
FieldsetHeader,
FieldsetLegend,
Label,
Text,
TextField,
TextFieldInput,
} from '@vega-ui/react';
import { useId, useState } from 'react';
const BILLING = { street: 'Unter den Linden 21', city: 'Berlin', postalCode: '10117' };
export default function HeaderWithAction() {
const id = useId();
const [address, setAddress] = useState({ street: '', city: '', postalCode: '' });
const change = (field: keyof typeof address, value: string) => {
setAddress({ ...address, [field]: value });
};
return (
);
}
```
## Comparison
### Quick Decision Rule
Use `Fieldset` when multiple related controls need one semantic group label. Use a plain `div` or `Card` only when the grouping is purely visual.
### `Fieldset` vs `Card`
Use `Fieldset` when:
- the grouping is semantic form structure
Use `Card` when:
- the container is only layout or presentation
### `Fieldset` vs `Separator`
Use `Fieldset` when:
- inputs belong to one named control group
Use `Separator` when:
- you only need visual division
### `Fieldset` vs `Heading`
Use `FieldsetLegend` when:
- the text labels one control group
Use `Heading` when:
- the text is document or section structure rather than native group semantics
### Choose This Component When
- several form controls belong to one named concept
- the group needs native `