# Switch

> Turns a setting on or off right away.

A switch turns one setting on or off, and the change applies right away, without a save button.

## When to use

- Use it for settings that apply at once, such as email notifications.
- Use a [Checkbox](https://design.sosialoka.tech/components/checkbox/) for a choice that is saved with a form, or for agreeing to terms.
- Write the label as the setting, not as a question: "Kirim notifikasi email".

_Live preview of the React and Vue versions: https://design.sosialoka.tech/components/switch/_

### Do and don't

- **Do:** Use a switch for a setting that applies the moment it changes.
- **Don't:** Don't put switches in a form that waits for a save button; use checkboxes there.

## Anatomy

1. Track, primary when on
2. Thumb
3. Label
4. Off state

A pill track that is `input` when off and `primary` when on, with a `background` thumb. It sits before its label and a one-sentence description, in a Field with the `horizontal` orientation.

## Variants

Two sizes: `default` and `sm`.

## Props

| React | Vue | Flutter | Type | Default | Use |
| --- | --- | --- | --- | --- | --- |
| `checked` / `defaultChecked` | `v-model` / `default-value` | `value` | boolean | `false` | On or off. |
| `onCheckedChange` | `@update:model-value` | `onChanged` | function | none | Runs when it changes. |
| `size` | `size` | `width` / `height` | `default`, `sm` | `default` | The size. |
| `disabled` | `disabled` | `enabled: false` | boolean | `false` | Blocks changes. |
| label in `FieldLabel` | label in `FieldLabel` | `label`, `sublabel` | text | none | Names the setting. |

## Code

**React**
```tsx
import { useId } from "react"
import { Field, FieldContent, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"

export default function SwitchDemo() {
  const id = useId()
  return (
    <Field orientation="horizontal" className="w-full max-w-sm">
      <Switch id={`${id}-email`} aria-describedby={`${id}-email-hint`} />
      <FieldContent>
        <FieldLabel htmlFor={`${id}-email`}>Kirim notifikasi email</FieldLabel>
        <FieldDescription id={`${id}-email-hint`}>Kabar rilis dan royalti masuk ke inbox kamu.</FieldDescription>
      </FieldContent>
    </Field>
  )
}
```

**Vue**
```vue
<script setup lang="ts">
import { useId } from "vue"
import { Field, FieldContent, FieldDescription, FieldLabel } from "@/components/ui/field"
import { Switch } from "@/components/ui/switch"

const id = useId()
</script>

<template>
  <Field orientation="horizontal" class="w-full max-w-sm">
    <Switch :id="`${id}-email`" :aria-describedby="`${id}-email-hint`" />
    <FieldContent>
      <FieldLabel :for="`${id}-email`">Kirim notifikasi email</FieldLabel>
      <FieldDescription :id="`${id}-email-hint`">Kabar rilis dan royalti masuk ke inbox kamu.</FieldDescription>
    </FieldContent>
  </Field>
</template>
```

**Flutter**
```dart
import 'package:flutter/widgets.dart';
import 'package:shadcn_ui/shadcn_ui.dart';

class SwitchDemo extends StatefulWidget {
  const SwitchDemo({super.key});

  @override
  State<SwitchDemo> createState() => _SwitchDemoState();
}

class _SwitchDemoState extends State<SwitchDemo> {
  bool email = false;

  @override
  Widget build(BuildContext context) {
    return ShadSwitch(
      value: email,
      onChanged: (value) => setState(() => email = value),
      label: const Text('Kirim notifikasi email'),
      sublabel: const Text('Kabar rilis dan royalti masuk ke inbox kamu.'),
    );
  }
}
```

## Install

**React**
```bash
npx shadcn@latest add https://design.sosialoka.tech/r/react/switch.json
```

**Vue**
```bash
npx shadcn-vue@latest add https://design.sosialoka.tech/r/vue/switch.json
```

## Accessibility

- It has `role="switch"` and `aria-checked`.
- Space toggles it; clicking the label toggles it too.
- Tie the description to it with `aria-describedby`.
