---
title: Toggle
description: A two-state button that can be either on or off.
icon: toggle-left
author:
  name: shadcn
  url: https://github.com/shadcn
search:
  keywords: [toggle button]
related:
  - /toggle-group
  - /switch
mode: wide
---

<PoweredBy
  packages={[
    { name: 'Base UI', url: 'https://base-ui.com/react/components/toggle' },
    { name: 'Shadcn UI', url: 'https://ui.shadcn.com/docs/components/toggle' },
  ]}
/>

### Installation

```package-install
npx shadcn@latest add @redpanda/toggle
```

<ComponentPreview name="toggle-demo" />

## When to use

Toggle provides a two-state button control. Use this decision tree:

```mermaid
graph TD;
    A[❓ Need toggle action?] --> B{Button-style toggle?};
    A --> C[⚠️ Use other input types];
    B --> D[✅ Use Toggle Component];
    B --> E{Switch-style needed?};
    D --> F{Toggle context?};
    E --> G[⚠️ Use Switch component];
    F --> H[✅ Toolbar Toggle];
    F --> I[✅ Feature Toggle];
    F --> J[✅ View Toggle];

    classDef recommended fill:#4ade80,stroke:#22c55e,stroke-width:2px,color:#000;
    classDef discouraged fill:#fbbf24,stroke:#f59e0b,stroke-width:2px,color:#000;
    classDef decision fill:#60a5fa,stroke:#3b82f6,stroke-width:2px,color:#fff;
    classDef neutral fill:#9ca3af,stroke:#6b7280,stroke-width:2px,color:#fff;

    class D,H,I,J recommended;
    class C,G discouraged;
    class A,B,E,F decision;
```

## Usage

```tsx
import { Toggle } from '@/components/ui/toggle';
```

```tsx
<Toggle>Toggle</Toggle>
```

## Examples

### Default

<ComponentPreview name="toggle-demo" description="A toggle component." />

### Outline

<ComponentPreview name="toggle-outline-demo" description="A toggle component using the outline variant." />

### With Text

<ComponentPreview name="toggle-with-text-demo" description="A toggle component with text." />

### Small

<ComponentPreview name="toggle-small-demo" description="A small toggle component." />

### Large

<ComponentPreview name="toggle-large-demo" description="A large toggle component." />

### Disabled

<ComponentPreview name="toggle-disabled-demo" description="A disabled toggle component." />

## Props

<div className="flex flex-row gap-x-3">
  <ExternalLink href="https://base-ui.com/react/components/toggle" text="Docs" />
  <ExternalLink href="https://base-ui.com/react/components/toggle#api-reference" text="API Reference" />
</div>

## Keyboard interactions

| Key                 | Action                               |
| ------------------- | ------------------------------------ |
| `Tab` to the toggle | Focus lands on the toggle.           |
| `Space` / `Enter`   | Toggles between pressed / unpressed. |

## Accessibility

- Renders as a real `<button>` with `aria-pressed="true" | "false"` — use it for **on/off** visual states (bold, italic,
  mute) rather than for navigation or mutually-exclusive selection (use Tabs / RadioGroup instead).
- Base UI also sets the compat `data-state="on" | "off"` attribute so existing Tailwind selectors keep working.
- Always provide a label — either visible text inside the toggle, or `aria-label` for icon-only toggles. Icon-only
  toggles without a label are unreadable to screen readers.
- `onPressedChange` uses the Base UI signature `(pressed: boolean, eventDetails) => void` — `eventDetails` lets you
  inspect the change reason or call `preventDefault()`. Single-argument callbacks remain compatible.

## Credits

- We use [Base UI](https://base-ui.com/react/components/toggle) for the toggle component.
- We take our inspiration from [Shadcn UI](https://ui.shadcn.com/docs/components/toggle) for the toggle style.