> ## Documentation Index
> Fetch the complete documentation index at: https://clementineds.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Switch Component: Instant On/Off Toggle for Settings

> Use Switch to toggle a single setting on or off with immediate effect, no Save button required. Distinct from Checkbox, which is for form state.

The `Switch` component renders a pill-shaped toggle that flips a single setting on or off. It is **Status: Draft** and is backed by [Mantine's Switch](https://mantine.dev/core/switch/) primitive. Clementine exports it from `@clementine-ds/ui` with the Clementine theme applied.

***

## When to use

* The change takes **immediate effect** — no Save button is required (e.g., enabling dark mode, toggling a notification preference, activating a feature flag).
* You have a **single binary setting** to control.
* The interface context makes "on/off" semantics self-evident.

## When not to use

* **Form submissions** where the user sets a value and then clicks Submit — use `Checkbox` instead. `Switch` implies instant effect; `Checkbox` implies pending form state.
* **Multiple related binary options** shown together — consider a `Checkbox` group to keep affordances consistent.
* **Mutually exclusive options** from a set — use `Radio` or `Select`.

***

## Usage

Import `Switch` from `@clementine-ds/ui`.

### Uncontrolled

```tsx theme={null}
import { Switch } from '@clementine-ds/ui';

export function NotificationToggle() {
  return (
    <Switch
      defaultChecked
      label="Email notifications"
      description="Receive a daily digest of activity."
    />
  );
}
```

### Controlled

```tsx theme={null}
import { useState } from 'react';
import { Switch } from '@clementine-ds/ui';

export function DarkModeToggle() {
  const [enabled, setEnabled] = useState(false);

  return (
    <Switch
      checked={enabled}
      onChange={(event) => setEnabled(event.currentTarget.checked)}
      label="Dark mode"
    />
  );
}
```

### With on/off inner labels

Use `onLabel` and `offLabel` to show text inside the track for added clarity.

```tsx theme={null}
import { Switch } from '@clementine-ds/ui';

export function FeatureFlag() {
  return (
    <Switch
      size="md"
      onLabel="ON"
      offLabel="OFF"
      label="Beta features"
      description="Enable experimental functionality."
    />
  );
}
```

### Disabled state

```tsx theme={null}
import { Switch, Stack } from '@clementine-ds/ui';

export function SwitchStates() {
  return (
    <Stack gap="sm">
      <Switch label="Active setting" defaultChecked />
      <Switch label="Inactive setting" />
      <Switch label="Cannot be changed" disabled />
      <Switch label="Locked on" defaultChecked disabled />
    </Stack>
  );
}
```

***

## Props

`SwitchProps` extends Mantine's `SwitchProps`, which itself extends the native `<input type="checkbox">` element. All standard HTML input attributes are forwarded to the underlying input.

| Prop | Type | Default | Description |
| - | - | - | - |
| `label` | `React.ReactNode` | — | Text label associated with the switch. Rendered beside the track. |
| `description` | `React.ReactNode` | — | Help text displayed below the label. |
| `error` | `React.ReactNode` | — | Error message displayed below the label; applies error styles. |
| `checked` | `boolean` | — | Controls the on/off state (controlled usage). |
| `defaultChecked` | `boolean` | — | Sets the initial on/off state (uncontrolled usage). |
| `disabled` | `boolean` | — | Prevents interaction and applies disabled styles. |
| `onChange` | `React.ChangeEventHandler<HTMLInputElement>` | — | Called when the switch is toggled. |
| `value` | `string` | — | Value used when the switch is part of a form or `Switch.Group`. |
| `name` | `string` | — | Name attribute for the underlying input, used in `FormData`. |
| `labelPosition` | `"left" \| "right"` | `"right"` | Position of the label relative to the track. |
| `size` | `MantineSize` | `"sm"` | Controls the size of the entire component (`"xs"` `"sm"` `"md"` `"lg"` `"xl"`). |
| `radius` | `MantineRadius \| number` | — | Border-radius of the track and thumb. |
| `color` | `MantineColor` | — | Theme color key or CSS color string for the track in the checked (on) state. |
| `onLabel` | `React.ReactNode` | — | Content rendered inside the track when the switch is on. |
| `offLabel` | `React.ReactNode` | — | Content rendered inside the track when the switch is off. |
| `thumbIcon` | `React.ReactNode` | — | Icon rendered inside the sliding thumb. |
| `withThumbIndicator` | `boolean` | — | When set, displays a colored dot inside the thumb that matches the track background. |
| `id` | `string` | auto-generated | Binds the input to its label element. |
| `rootRef` | `Ref<HTMLDivElement>` | — | Ref forwarded to the root wrapper element. |
| `wrapperProps` | `React.ComponentProps<"div">` | — | Additional props spread onto the root wrapper `<div>`. |

***

## Interaction states

| State | Description |
| - | - |
| `off` | Default unchecked state. Track is in its neutral color. |
| `on` | Checked state. Track fills with the active color; thumb slides to the end. |
| `hover` | Cursor moves over the track or label. |
| `focus` | Keyboard focus ring appears on the track (`:focus-visible`). |
| `disabled` | Track and label are greyed out; pointer events are suppressed. |

The thumb animates between positions on state change. The transition completes in 200 ms or less, in line with the Clementine motion spec.

***

## Accessibility

* The underlying element is `<input type="checkbox" role="switch">`. The `role="switch"` attribute communicates the on/off semantics to assistive technologies, distinct from a standard checkbox.
* `aria-checked` is automatically managed by the browser based on the `checked` state of the underlying input.
* Always provide a `label` prop or an `aria-label` attribute. An unlabeled switch is not announced usefully by screen readers.

```tsx theme={null}
// ✅ Labeled via prop
<Switch label="Email notifications" />

// ✅ Labeled via aria-label (when a visible label is not needed)
<Switch aria-label="Toggle dark mode" />

// ❌ No label — screen readers cannot identify the purpose of this switch
<Switch />
```

***

> [!WARNING]
>
> **Draft status.** The `Switch` component is currently **Draft**. Verify `aria-checked` is correctly exposed by the underlying Mantine implementation and that the thumb animation completes within the required 200 ms threshold before shipping to production.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.