> Leaf UI 0.17.3 · Package: @ifhover/leaf-ui · Source: c3221834f84f2f48481a2054026b713456f8e5dc
> Browser documentation: https://ifhover.github.io/leaf-ui/en/components/switch.html

> For AI agents: the complete documentation index is available at https://ifhover.github.io/leaf-ui/en/llms.txt, the full documentation bundle is available at https://ifhover.github.io/leaf-ui/en/llms-full.txt.

# Switch

Turn a setting on or off immediately.


## Basic usage

Use the switch to toggle on/off state and provide an associated label.


Enable notifications

basic.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/switch/basic.tsx"
import { Switch } from '@ifhover/leaf-ui';

export function SwitchBasic() {
  return <Switch>Enable notifications</Switch>;
}
```

Expand code


## Examples

### Disabled and loading

`disabled` prevents interaction. Set `loading` while saving to prevent repeated changes; the application performs the async operation.


Disabled

Enable notifications

Loading

Enable notifications

states.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/switch/states.tsx"
import { Flex, Grid, Switch, Text } from '@ifhover/leaf-ui';

export function SwitchStates() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      <Text tone="muted">Disabled</Text>
      <Flex align="center" wrap>
        <Switch disabled defaultChecked>
          Enable notifications
        </Switch>
      </Flex>
      <Text tone="muted">Loading</Text>
      <Flex align="center" wrap>
        <Switch loading defaultChecked>
          Enable notifications
        </Switch>
      </Flex>
    </Grid>
  );
}
```

Expand code

### Sizes

Use `size` to set the switch size.


Small

Enable notifications

Medium

Enable notifications

Large

Enable notifications

sizes.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/switch/sizes.tsx"
import { Flex, Grid, Switch, Text } from '@ifhover/leaf-ui';
import { Fragment } from 'react';

const options = [
  { value: 'sm', label: 'Small' },
  { value: 'md', label: 'Medium' },
  { value: 'lg', label: 'Large' },
] as const;

export function SwitchSizes() {
  return (
    <Grid columns={{ xs: 1, sm: 2 }} gap={16} align="center">
      {options.map(({ value, label }) => (
        <Fragment key={value}>
          <Text tone="muted">{label}</Text>
          <Flex align="center" wrap>
            <Switch size={value}>Enable notifications</Switch>
          </Flex>
        </Fragment>
      ))}
    </Grid>
  );
}
```

Expand code

### Controlled state

Pass `checked` and read the boolean from `event.target.checked` in `onChange`.


Receive emailEmail notifications enabled

controlled.tsx

Copy code

```tsx lineNumbers file="../../../src/examples/en/switch/controlled.tsx"
import { Flex, Switch, Text } from '@ifhover/leaf-ui';
import { useState } from 'react';

export function SwitchControlled() {
  const [checked, setChecked] = useState(true);
  return (
    <Flex direction="column" gap="md" align="start">
      <Switch checked={checked} onChange={(event) => setChecked(event.target.checked)}>
        Receive email
      </Switch>
      <Text tone="muted" role="status">
        {checked ? 'Email notifications enabled' : 'Email notifications disabled'}
      </Text>
    </Flex>
  );
}
```

Expand code

With `name`, an enabled, checked switch submits its `value`. Unchecked, disabled or loading switches are not submitted. Uncontrolled switches return to `defaultChecked` on form reset; reset application state as well for a controlled switch.


## API

### Switch API

Configure checked state, form submission and interaction state.

Supports native checkbox attributes such as `name`, `value`, `required` and `form`. Provide text or `aria-label` as its accessible name. `className` and `style` apply to the label container.

| Property         | Type                                   | Default | Description                                      |
| ---------------- | -------------------------------------- | ------- | ------------------------------------------------ |
| `size`           | `'sm' \| 'md' \| 'lg'`                 | `'md'`  | Control size                                     |
| `loading`        | `boolean`                              | `false` | Show loading and disable interaction             |
| `checked`        | `boolean`                              | —       | Controlled switch state.                         |
| `defaultChecked` | `boolean`                              | —       | Initial switch state for uncontrolled usage.     |
| `onChange`       | `ChangeEventHandler<HTMLInputElement>` | —       | Read the switch state from event.target.checked. |
| `disabled`       | `boolean`                              | `false` | Disable interaction.                             |
| `children`       | `ReactNode`                            | —       | Clickable text label.                            |
| `ref`            | `Ref<HTMLInputElement>`                | —       | DOM reference                                    |
