---
layout: ~/layouts/MdxDocLayout.astro
title: "Switch"
description: "A two-state button that can be either on or off."
sourceFile: "components/switch"
baseUIComponent: "switch"
---

import ComponentExample from "~/components/docs/ComponentExample.astro";
import ComponentSection from "~/components/docs/ComponentSection.astro";
import PropsTable from "~/components/docs/PropsTable.astro";
import {
  SwitchBasicDemo,
  SwitchOffDemo,
  SwitchOnDemo,
  SwitchDisabledDemo,
  SwitchNeutralDemo,
  SwitchNeutralStatesDemo,
  SwitchVariantsDemo,
  SwitchSizesDemo,
  SwitchCustomIdDemo,
  SwitchGroupDemo,
  SwitchLegendSrOnlyDemo,
  SwitchLegendCustomDemo,
} from "~/components/demos/SwitchDemo";

{/* Hero Demo */}

<ComponentSection>
  <ComponentExample demo="SwitchBasicDemo">
    <SwitchBasicDemo client:visible />
  </ComponentExample>
</ComponentSection>

{/* Installation */}

<ComponentSection>

## Installation

### Barrel

```tsx
import { Switch } from "@cloudflare/kumo";
```

### Granular

```tsx
import { Switch } from "@cloudflare/kumo/components/switch";
```

</ComponentSection>

{/* Usage */}

<ComponentSection>

## Usage

```tsx
import { Switch } from "@cloudflare/kumo";
import { useState } from "react";

export default function Example() {
  const [checked, setChecked] = useState(false);

  return (
    <Switch checked={checked} onCheckedChange={(val) => setChecked(val)} />
  );
}
```

</ComponentSection>

{/* Examples */}

<ComponentSection>

## Examples

### Off State

<ComponentExample demo="SwitchOffDemo">
  <SwitchOffDemo client:visible />
</ComponentExample>

### On State

<ComponentExample demo="SwitchOnDemo">
  <SwitchOnDemo client:visible />
</ComponentExample>

### Disabled

<ComponentExample demo="SwitchDisabledDemo">
  <SwitchDisabledDemo client:visible />
</ComponentExample>

### Variants

<p>
  The Switch supports two variants: `default` (blue when on) and `neutral`
  (monochrome). Both use a squircle shape.
</p>
<ComponentExample demo="SwitchVariantsDemo">
  <SwitchVariantsDemo client:visible />
</ComponentExample>

### Neutral Variant

<p>
  The neutral variant uses monochrome colors and a squircle shape, ideal for
  subtle, less prominent toggles.
</p>
<ComponentExample demo="SwitchNeutralDemo">
  <SwitchNeutralDemo client:visible />
</ComponentExample>

### Neutral States

<ComponentExample demo="SwitchNeutralStatesDemo">
  <SwitchNeutralStatesDemo client:visible />
</ComponentExample>

### Sizes

<p>Three sizes available: `sm`, `base` (default), and `lg`.</p>
<ComponentExample demo="SwitchSizesDemo">
  <SwitchSizesDemo client:visible />
</ComponentExample>

### Custom ID

<p>
  When a custom `id` is provided, clicking the label still toggles the switch.
  The `id` is forwarded to Base UI so the label's `htmlFor` stays in sync.
</p>
<ComponentExample demo="SwitchCustomIdDemo">
  <SwitchCustomIdDemo client:visible />
</ComponentExample>

### Switch Group

<p>
  Group related switches with `Switch.Group`. Provides a shared legend,
  description, and error message for the group.
</p>
<ComponentExample demo="SwitchGroupDemo">
  <SwitchGroupDemo client:visible />
</ComponentExample>

### Visually Hidden Legend

<p>
  Use `Switch.Legend` with `className="sr-only"` to keep the legend accessible
  to screen readers while hiding it visually. This is useful when the group is
  already labeled by a parent `Field` or heading, and showing the legend would
  create a redundant label.
</p>
<ComponentExample demo="SwitchLegendSrOnlyDemo">
  <SwitchLegendSrOnlyDemo client:visible />
</ComponentExample>

### Custom Legend Styling

<p>
  `Switch.Legend` accepts `className` for full control over legend presentation.
  Use it instead of the `legend` string prop when you need custom typography,
  colors, or layout.
</p>
<ComponentExample demo="SwitchLegendCustomDemo">
  <SwitchLegendCustomDemo client:visible />
</ComponentExample>

</ComponentSection>

{/* API Reference */}

<ComponentSection>

## API Reference

### Switch

<p>Individual switch toggle with built-in label.</p>
<PropsTable component="Switch" />

### Switch.Group

<p>
  Container for multiple switches with legend, description, and error support.
</p>
<PropsTable component="Switch.Group" />

### Switch.Legend

<p>
  Composable legend sub-component for Switch.Group. Accepts `className` for full
  styling control (e.g. `className="sr-only"` to visually hide). Use instead of
  the `legend` string prop when you need custom legend styling.
</p>
<PropsTable component="Switch.Legend" />

### Switch.Item

<p>Individual switch within Switch.Group.</p>
<PropsTable component="Switch.Item" />

</ComponentSection>
