Source: https://monarchui.dev/components/switch/

Components · Forms

# Switch

Immediate on/off setting.

@rookcom/monarch-react

Component

## Settings row

## Usage examples

The example at the top of the page is the only one for this component.

## Purpose

An on/off setting that applies immediately, with an optional inline label and description. Built on Radix Switch.

### Use when

- A setting takes effect as soon as it is toggled (notifications, two-step sign-in).

### Avoid when

- The choice is submitted with a form: use Checkbox.

## Design principles

- The inline label sits before the control (`.mn-choice--switch`), reading like a settings row.
- Omit `label` when the switch sits in a Field or SettingsRow that labels it.

## API reference

```tsx
import { Switch } from '@rookcom/monarch-react';
```

| Export | Kind | Rendering | Root class |
| --- | --- | --- | --- |
| `Switch` | component | client | `.mn-switch-` |

Forwards its ref to the Radix Switch root (a `<button role="switch">`).

With `label`, `className` goes on the `.mn-choice` wrapper; without it, on the switch.

Generated from the TypeScript declarations of `packages/react/src/components/forms/switch`.

## Properties

### `Switch`

An on/off setting that applies immediately. For choices that are submitted with a form, prefer Checkbox.

| Prop | Type | Description |
| --- | --- | --- |
| `asChild` | `boolean` |  |
| `children` | `ReactNode` |  |
| `className` | `string` |  |
| `description` | `ReactNode` |  |
| `disabled` | `boolean` |  |
| `id` | `string` |  |
| `label` | `ReactNode` |  |
| `size` | `"sm" \| "md"` |  |

## Variants

| Prop | Values | Description |
| --- | --- | --- |
| `size` | `'sm'``'md'` | Track size. Default `md`. Exposed as `data-size`. |

## States

| State | Exposed as | Behaviour |
| --- | --- | --- |
| Checked | `data-state='checked'` | Accent track with the thumb moved to the end. |
| Disabled | `disabled` | Dimmed; the inline label uses the disabled text colour. |
| Focus | – | Visible focus ring on `:focus-visible`. |

## Interaction behaviour

- Click on the switch or its inline label toggles it.
- `description` renders under the label and is added to `aria-describedby`.

## Keyboard support

| Keys | Action |
| --- | --- |
| Tab | Moves focus to the switch. |
| Space | Toggles the switch. |

## Accessibility

Role

switch

Accessible name

The inline

label

, a FieldLabel, or

aria-label

.

- State is exposed as `aria-checked`.
- Inside a Field, `aria-invalid` and `aria-describedby` come from the Field.

## Responsive behaviour

This section is incomplete

No responsive behaviour is defined for the switch itself.

## Theme support

- Colours are semantic tokens; the checked track follows the product accent.

## Do and don't

### Do

- Save the setting as soon as it changes.

### Don't

- Do not put a switch in a form that needs a Save button; use Checkbox.

## Related components

- [Checkbox](https://monarchui.dev/components/checkbox/): Choices submitted with a form.
- [SettingsSection](https://monarchui.dev/components/settings-section/): SettingsRow lays out a labelled switch on settings pages.
- [SwitchSettingsList](https://monarchui.dev/components/switch-settings-list/): Planned list of switch settings.

## Dependencies

| Kind | Depends on |
| --- | --- |
| npm packages | `@radix-ui/react-switch``react` |
| Monarch components | [Field](https://monarchui.dev/components/form-field/) |

## Testing coverage

- Toggles with click and Space and exposes switch semantics (`aria-checked`).

| Check | Covered |
| --- | --- |
| Axe in jsdom | Yes |
| Server rendering | Yes |
| Browser suites | Visual baselines: /__gallery |

Tests: `packages/react/src/components/forms/switch`

## All example code

### Settings row

```tsx
import { Switch } from '@rookcom/monarch-react';

<Switch
  label="Two-step sign-in"
  description="Ask for a PIN on new devices."
  defaultChecked
/>
<Switch label="Compact rail" size="sm" />
```