---
title: "Switch"
description: "An on/off switch for settings that apply instantly. The state is announced as checked."
kind: component
id: C-013
registry: "switch"
docs: "https://koten.codehive.com.co/components/switch"
markdown: "https://koten.codehive.com.co/md/components/switch.md"
install: "npx shadcn@latest add https://koten.codehive.com.co/r/switch.json"
language: en
---

# Switch · スイッチ

> Component C-013 in the Koten UI catalog.

An on/off switch for settings that apply instantly. The state is announced as checked.

> Japanese labels in this page are documentation metadata. Keep the consumer UI in the product's language and do not add Japanese decoration unless the user asks (R-031).

## Install

Install `koten-theme` first when the project does not have Koten tokens yet. Use the runner of your project.

```bash
# Node
npx shadcn@latest add https://koten.codehive.com.co/r/switch.json

# Bun
bunx shadcn@latest add https://koten.codehive.com.co/r/switch.json
```

## Files

- `@/components/ui/switch.tsx`
- `@/lib/koten/cn.ts`
- `@/lib/koten/format.ts`
- `@/lib/koten/intl.ts`
- `@/lib/koten/labels.ts`
- `@/lib/koten/provider.tsx`

## Reference

- Upstream primitive: https://base-ui.com/react/components/switch

## Examples

### States

On, off and disabled; the label sits on the left and the control on the right.

```tsx
<Switch
  label="Order notifications"
  description="Alerts for new and cancelled orders."
  defaultChecked
/>
<Switch label="Weekly summary" description="Every Monday at 09:00." />
<Switch label="SMS alerts" description="This channel is not available." disabled />
```

### Controlled state

checked and onCheckedChange let the rest of the interface react to the switch.

```tsx
const [visible, setVisible] = useState(true);

<Switch
  label="Storefront visibility"
  description="Hide the product without unpublishing it."
  checked={visible}
  onCheckedChange={setVisible}
/>
<p className="text-2xs text-muted">
  Storefront: <span className="font-semibold text-ink">{visible ? "visible" : "hidden"}</span>
</p>
```

### Use inside a form

The switch starts on and the error explains what is missing before publishing; the button confirms the action.

```tsx
<form
  className="grid w-full max-w-sm gap-[var(--koten-gap)]"
  onSubmit={(event) => event.preventDefault()}
>
  <div className="grid gap-1">
    <Switch
      label="Publish to storefront"
      description="The product goes live as soon as you save."
      defaultChecked
    />
    <p role="alert" className="text-2xs leading-relaxed text-danger">
      Add a cover image before publishing.
    </p>
  </div>
  <div className="flex justify-end">
    <Button type="submit" variant="primary">Publish product</Button>
  </div>
</form>
```

## Props

| Prop | Type | Default | Notes |
| --- | --- | --- | --- |
| `label` | `ReactNode` | `—` | Visible content and accessible name; required. |
| `description` | `ReactNode` | `—` | Renders under the control, outside the accessible name. |
| `checked / defaultChecked` | `boolean` | `false` | Controlled or uncontrolled. |
| `onCheckedChange` | `(checked: boolean, event: Event) => void` | `—` | Fires when the switch turns on or off. |
| `disabled` | `boolean` | `false` | Blocks the switch and dims it. |
| `name` | `string` | `—` | Name the state travels with in the form. |

## Accessibility

- The control keeps the switch role and announces checked on change, without relying on the thumb color.
- label wraps the switch and provides the accessible name; description stays outside.
- The thumb is decorative: state is read from the control, not from its position.

## Sources

- Catalog page: https://koten.codehive.com.co/components/switch
- Markdown: https://koten.codehive.com.co/md/components/switch.md
- Repository: https://github.com/codehive-colombia/koten