# Toggle

A two-state button that can be toggled on or off.

> For the complete documentation index, see [llms.txt](/llms.txt). Markdown variants are available by appending `.md` to any URL or sending an `Accept: text/markdown` header. An agent skill is available at [/.well-known/agent-skills/site-skill.md](/.well-known/agent-skills/site-skill.md).

<ComponentPreview name="toggle" title="toggle.tsx">
<Component />
</ComponentPreview>

Toggle is a two-state button rendered as a native `<button>` with `aria-pressed`. It supports `default` and `outline` variants, `sm` / `default` / `lg` sizes, and pressed / disabled states.

## Installation [#installation]

<CodeTabs>
<TabsList>
<TabsTrigger value="cli">
Command
</TabsTrigger>

<TabsTrigger value="manual">
Manual
</TabsTrigger>
</TabsList>

<TabsContent value="cli">
```bash
npx frakment add toggle
```
</TabsContent>

<TabsContent value="manual">
<Steps>
<Step>
Install the following dependencies:
</Step>

```bash
npm install class-variance-authority
```

<Step>
Copy and paste the following code into your project.
</Step>

<ComponentSource name="toggle" title="components/ui/toggle.tsx" />

<Step>
Update the import paths to match your project setup.
</Step>
</Steps>
</TabsContent>
</CodeTabs>

## Usage [#usage]

```tsx title="toggle.tsx"
import { Toggle } from "@/components/ui/toggle";
<DocsBaseSwitcher base="web" component="toggle" className="mb-6" />
```

```tsx
<Toggle aria-label="Toggle italic">
  <ItalicIcon />
  Italic
</Toggle>
```

## Anatomy [#anatomy]

```tsx
<Toggle>
  <Icon />
  Label
</Toggle>
```

- **Toggle** — native `<button>`; accepts `variant`, `size`, `pressed`, `defaultPressed`, `onPressedChange`, `as`
- Icons and text are children; the pressed state styles icon fills via `group-aria-pressed/toggle:`

## Examples [#examples]

### Outline [#outline]

Pass `variant="outline"` for a bordered toggle.

<ComponentPreview name="toggle-outline" title="toggle-outline.tsx" src="examples/toggle-outline.tsx">
<l />
</ComponentPreview>

```tsx
<Toggle variant="outline" aria-label="Toggle italic">
  <ItalicIcon />
  Italic
</Toggle>
```

### Text [#text]

Default variant — no border, transparent background.

<ComponentPreview name="toggle-text" title="toggle-text.tsx" src="examples/toggle-text.tsx">
<h />
</ComponentPreview>

```tsx
<Toggle aria-label="Toggle italic">
  <ItalicIcon />
  Italic
</Toggle>
```

### Sizes [#sizes]

`size` accepts `sm`, `default`, and `lg`.

<ComponentPreview name="toggle-sizes" title="toggle-sizes.tsx" src="examples/toggle-sizes.tsx">
<d />
</ComponentPreview>

```tsx
<Toggle size="sm">Small</Toggle>
<Toggle size="default">Default</Toggle>
<Toggle size="lg">Large</Toggle>
```

### Disabled [#disabled]

Set `disabled` on the toggle to lock interaction.

<ComponentPreview name="toggle-disabled" title="toggle-disabled.tsx" src="examples/toggle-disabled.tsx">
<o />
</ComponentPreview>

```tsx
<Toggle disabled>Disabled</Toggle>
<Toggle variant="outline" disabled>Disabled</Toggle>
```

## In Context [#in-context]

### Toolbar toggle [#toolbar-toggle]

<ComponentPreview name="toggle-toolbar" title="toggle-toolbar.tsx" src="examples/toggle-toolbar.tsx">
<ToggleToolbar />
</ComponentPreview>

## API Reference [#api-reference]

Extends `React.ComponentProps<"button">`.

<PropsTable rows={[{"name":"variant","type":"\"default\" | \"outline\"","defaultValue":"\"default\"","description":"Visual style."},{"name":"size","type":"\"sm\" | \"default\" | \"lg\"","defaultValue":"\"default\"","description":"Toggle size."},{"name":"pressed","type":"boolean","defaultValue":"","description":"Controlled pressed state."},{"name":"defaultPressed","type":"boolean","defaultValue":"false","description":"Initial pressed state (uncontrolled)."},{"name":"onPressedChange","type":"(pressed: boolean) => void","defaultValue":"","description":"Called when the pressed state changes."}]} />

## Controlled [#controlled]

```tsx
const [pressed, setPressed] = React.useState(false)
<Toggle pressed={pressed} onPressedChange={setPressed} />
```

## States [#states]

| State | How |
| :-- | :-- |
| Off | default |
| On | `pressed` prop |
| Disabled | `disabled` prop |

## Keyboard [#keyboard]

| Key | Action |
| :-- | :-- |
| `Space` / `Enter` | Toggle |

## Data Attributes [#data-attributes]

| Attribute | Values |
| :-- | :-- |
| `data-slot` | `toggle` |
| `data-state` | `on` \| `off` |
| `data-disabled` | `true` |

## Variants [#variants]

| Variant | Use case |
| :-- | :-- |
| `default` | Solid pressed state |
| `outline` | Bordered, transparent until pressed |

## Accessibility [#accessibility]

- `Toggle` renders a button with `aria-pressed`.
- Provide `aria-label` when the toggle is icon-only.
- Keyboard: Space toggles.

## Best Practices [#best-practices]

- **Icon-only toggles need a label.** `aria-label` is not optional.
- **Use `ToggleGroup` for multiple toggles.** Standalone toggles read as buttons.
- **Persist the state.** Toggles are stateful, not one-shot.
## Related Components [#related-components]

- [Toggle Group](/docs/components/web/toggle-group) — set of toggles
- [Switch](/docs/components/web/switch) — boolean setting