# Switch
## Summary
`Switch` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) for immediate binary settings, with a native input for semantics and state and an indicator for the visible track and thumb. It is the binary-toggle layer when the UI should read as on or off right now, not as one deferred form choice among others.
## Imports
```tsx
import {
Switch,
SwitchIndicator,
SwitchInput,
type SwitchProps,
type SwitchSize,
type SwitchVariant,
} from '@vega-ui/react';
```
## Exported Types
- `SwitchProps`
- `SwitchInputProps`
- `SwitchIndicatorProps`
- `SwitchSize`
- `SwitchVariant`
## Minimal Composition
```tsx
import { Label, Switch, SwitchIndicator, SwitchInput } from '@vega-ui/react';
export default function MinimalComposition() {
return (
);
}
```
## Required Parts
- `Switch`: root track and context surface
- `SwitchInput`: the native `role='switch'` checkbox — focus, keyboard, state and form value
- `SwitchIndicator`: visible switch thumb and track state
## Optional Parts
- None. The visible text goes outside the `Switch` root.
## Composition Order
1. `Switch`
2. `SwitchInput`
3. `SwitchIndicator`
4. a separate `Label` with `htmlFor` pointing at the `SwitchInput` `id`, or `aria-label` on `SwitchInput`
## Variants
- Sizes: `sm`, `md`, `lg`
- Variants: `primary`, `secondary`
- States: unchecked, checked, disabled
## Edge Cases
- Switches imply immediate binary state, not a deferred exclusive choice.
- Give `SwitchInput` a `name` when the control belongs to a native form.
- Labels should describe the controlled feature, not the toggle action itself.
- If the binary choice is only one line inside a larger checklist or form submission flow, `Checkbox` may communicate intent better.
## Common Mistakes
- Using a switch for deferred form choices.
- Writing labels like "Turn on" instead of naming the setting.
- Leaving out `SwitchInput`, which is the actual control.
## Examples
### Basic
#### Basic: settings rows with descriptions
The `Switch` root is the track itself, so the visible title is a separate `Label` linked to `SwitchInput` with `htmlFor`/`id`, and the description is attached with `aria-describedby`. `flex-shrink: 0` keeps the track from shrinking next to long text.
```tsx
import { Label, Switch, SwitchIndicator, SwitchInput, Text } from '@vega-ui/react';
const settings = [
{ id: 'auto-updates', title: 'Automatic updates', description: 'Install security patches overnight.', checked: true },
{ id: 'usage-data', title: 'Share usage data', description: 'Help us improve with anonymous diagnostics.', checked: false },
{ id: 'beta-features', title: 'Beta features', description: 'Try new tools before they are released.', checked: false },
];
export default function SettingsToggle() {
return (
{settings.map((setting) => (
{setting.description}
))}
);
}
```
### Controlled/Stateful
#### Controlled/Stateful: immediate effect
A switch applies its change right away. The parent owns `checked`, updates it from `event.currentTarget.checked`, and the status line below reflects the new state at once.
```tsx
import { useState } from 'react';
import { Label, Switch, SwitchIndicator, SwitchInput, Text } from '@vega-ui/react';
export default function ParentOwnedSwitchState() {
const [maintenance, setMaintenance] = useState(false);
return (
setMaintenance(event.currentTarget.checked)}
/>
{maintenance ? 'Visitors see the maintenance page. Admins can still sign in.' : 'The site is live for everyone.'}
);
}
```
### Form/Integration
#### Form/Integration: reading values with FormData
A switch submits like a checkbox: the `name` is present with the value `on` when it is on and absent when it is off, so read it with `FormData.has`. Reset restores `defaultChecked`.
```tsx
import { FormEvent, useState } from 'react';
import { Button, Fieldset, FieldsetLegend, Label, Switch, SwitchIndicator, SwitchInput, Text } from '@vega-ui/react';
const privacy = [
{ name: 'profile-public', title: 'Public profile', checked: true },
{ name: 'show-email', title: 'Show email address', checked: false },
{ name: 'search-indexing', title: 'Allow search engines to index my profile', checked: false },
];
export default function FormDataSubmission() {
const [result, setResult] = useState('');
const handleSubmit = (event: FormEvent) => {
event.preventDefault();
const data = new FormData(event.currentTarget);
const entries = privacy.map((item) => `${item.name}=${data.has(item.name) ? 'on' : 'off'}`);
setResult(entries.join(', '));
};
return (
);
}
```
### Layout/Overlay
#### Layout/Overlay: toggles inside a sheet
A short list of settings in a `Sheet`, named by its heading through `aria-labelledby`. The switches apply immediately, so the sheet needs no submit button, only a close button.
```tsx
import { CSSProperties } from 'react';
import {
Button,
Heading,
Icon,
IconButton,
Label,
Sheet,
SheetClose,
SheetContent,
SheetHandle,
SheetTrigger,
Switch,
SwitchIndicator,
SwitchInput,
} from '@vega-ui/react';
import { XIcon } from '@vega-ui/icons';
const options = [
{ id: 'sheet-autoplay', title: 'Autoplay next episode', checked: true },
{ id: 'sheet-subtitles', title: 'Always show subtitles', checked: false },
{ id: 'sheet-data-saver', title: 'Data saver on mobile networks', checked: true },
];
export default function OverlayToggleList() {
return (
Playback settings
{options.map((option) => (
))}
);
}
```
### Error
#### Error: rule across several switches
Turning both channels off breaks a product rule. The error appears right away, both inputs get `aria-invalid` and `aria-describedby` pointing at it, and turning either channel back on clears it. `Switch` has no invalid style of its own, so the message carries the state.
```tsx
import { useState } from 'react';
import { Fieldset, FieldsetLegend, HelperText, Label, Switch, SwitchIndicator, SwitchInput } from '@vega-ui/react';
export default function AtLeastOneChannel() {
const [email, setEmail] = useState(true);
const [push, setPush] = useState(false);
const invalid = !email && !push;
const describedBy = invalid ? 'channels-error' : undefined;
return (
);
}
```
### Disabled
#### Disabled: master switch disables a group
Turning off the master switch sets `disabled` on the `Fieldset`, and every switch inside inherits it natively. The security alerts switch is always disabled and explains why through `aria-describedby`.
```tsx
import { useState } from 'react';
import { Fieldset, FieldsetLegend, HelperText, Label, Switch, SwitchIndicator, SwitchInput } from '@vega-ui/react';
const kinds = [
{ id: 'notify-comments', title: 'Comments', checked: true },
{ id: 'notify-mentions', title: 'Mentions', checked: true },
{ id: 'notify-reviews', title: 'Review requests', checked: false },
];
export default function DisabledSwitches() {
const [enabled, setEnabled] = useState(true);
return (
setEnabled(event.currentTarget.checked)} />
);
}
```
### Edge
#### Edge: saving to a server
The switch flips optimistically, then waits for the request. While saving it is `aria-busy` and `aria-disabled` instead of `disabled`, so focus stays on it; a failed request reverts the value and the reason is announced through `aria-live`. Turning on two-factor authentication fails on purpose.
```tsx
import { useState } from 'react';
import { Label, Switch, SwitchIndicator, SwitchInput, Text } from '@vega-ui/react';
const settings = [
{ id: 'weekly-digest', title: 'Weekly email digest' },
{ id: 'two-factor', title: 'Require two-factor authentication' },
];
const saveSetting = (id: string, value: boolean) => new Promise((resolve, reject) => {
setTimeout(() => {
if (id === 'two-factor' && value) {
reject(new Error('Add a verified phone number first.'));
return;
}
resolve();
}, 1200);
});
export default function AsyncToggleWithPending() {
const [values, setValues] = useState>({ 'weekly-digest': false, 'two-factor': false });
const [pending, setPending] = useState>({});
const [status, setStatus] = useState>({});
const handleChange = async (id: string, next: boolean) => {
if (pending[id]) return;
const previous = values[id];
setValues((current) => ({ ...current, [id]: next }));
setPending((current) => ({ ...current, [id]: true }));
setStatus((current) => ({ ...current, [id]: 'Saving…' }));
try {
await saveSetting(id, next);
setStatus((current) => ({ ...current, [id]: 'Saved.' }));
} catch (error) {
setValues((current) => ({ ...current, [id]: previous }));
setStatus((current) => ({ ...current, [id]: `Not saved: ${(error as Error).message}` }));
}
setPending((current) => ({ ...current, [id]: false }));
};
return (
);
}
```
#### Edge: right-to-left layout
Settings rows inside `dir='rtl'`. The row layout mirrors through flexbox; check that the thumb moves toward the inline end of the track when the switch turns on.
```tsx
import { Label, Switch, SwitchIndicator, SwitchInput } from '@vega-ui/react';
const settings = [
{ id: 'rtl-dark-mode', title: 'الوضع الداكن', checked: true },
{ id: 'rtl-notifications', title: 'الإشعارات', checked: false },
];
export default function RightToLeft() {
return (
{settings.map((setting) => (
))}
);
}
```
## Anatomy
### Overview
`Switch` is a [compound component](https://vega-ui.dev/docs/glossary/#compound-component) for one immediate binary setting, with a native input for semantics and state and an indicator for the visible thumb and track.
### Required Parts
#### `Switch`
Required. Owns size and variant context for the switch.
#### `SwitchIndicator`
Required. Renders the visible switch thumb and track surface.
#### `SwitchInput`
Required. The visually hidden native checkbox with `role='switch'`: focus, keyboard, checked state and form value come from it.
### Optional Parts
`Switch` has no optional parts. The `Switch` root is the track itself, so the visible text lives outside it and is linked with `htmlFor`.
### Composition Order
1. `Switch`
2. `SwitchInput`
3. `SwitchIndicator`
4. a separate `Label` with `htmlFor` pointing at the `SwitchInput` `id`, or `aria-label` on `SwitchInput`
### Valid Composition Patterns
Name the switch with a separate `Label` whose `htmlFor` matches the `SwitchInput` `id`, or, when there is no visible text, with `aria-label` on `SwitchInput`. Do not wrap `Switch` in another `