# Toggle

A standalone two-state button that can be pressed or unpressed.

- Category: Core Elements
- Page: https://wunderui.com/components/toggle
- Tier: Free

## Install

```bash
npx wunderui-cli add toggle
```

## Import

```tsx
import { Toggle, ToggleButton } from "@/components/ui/toggle"
```

## Minimal usage

Then use it:

```tsx
import { Bold } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"

export function BoldToggle() {
  return (
    <Toggle aria-label="Bold" defaultPressed>
      <Bold strokeWidth={1.5} />
    </Toggle>
  )
}
```

Expected result: A 36 px square button with a bold icon on the indigo tint. Press it, or press Enter or Space while it has focus, to turn it off.

## Usage

```tsx
import { Bold } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"

export function Example() {
  return (
    <Toggle>
      <Bold strokeWidth={1.5} />
      Bold
    </Toggle>
  )
}
```

## When to use

### Use Toggle for

- A state people switch on the spot and see at once, such as bold text, mute or a grid overlay
- Filters that stay applied while people read a list
- Icon buttons in a toolbar that keep a mode

### Use something else

- [Switch](https://wunderui.com/components/switch) for a saved setting, with its label beside it
- [Checkbox](https://wunderui.com/components/checkbox) for a choice in a form that is submitted
- [Radio Button Group](https://wunderui.com/components/radio-button-group) for one choice among a few options that look like buttons (a radio group, not a set of toggles)
- [Button](https://wunderui.com/components/button) for an action that does not stay on

## Keyboard

The toggle is a native button, so the browser provides focus and activation.

| Key | Action |
|---|---|
| `Tab` or `Shift+Tab` | Moves focus to the next or previous toggle. A disabled toggle is skipped. |
| `Enter` or `Space` | Presses or releases the focused toggle and calls `onPressedChange`. |

## Behavior

What the toggle does with state, naming, looks, sizes and motion.

- **Pressed state:** A toggle holds one boolean. Give it a default to start, or control it with a pressed value and change handler, and the state is exposed as aria-pressed.
- **Naming:** A toggle is named by its text. An icon-only toggle has none so it needs an aria-label, and the name stays the same in both states.
- **Looks:** Off is a white fill with a control border, light on hover and subtle while pressed. On is the indigo tint with its border and text, and the indigo tone is tinted at rest and solid while pressed.
- **Sizes:** Five fixed heights: 32, 36, 40, 44 and 48 px, which don't follow density. The icon is 16 px at every size, and the label is 14 px up to large, 16 px at xl and 18 px at 2xl.
- **Disabled:** A disabled toggle is a real disabled button. It keeps its state, drops to 40 % opacity, ignores the pointer and is skipped by Tab.
- **Focus:** Keyboard focus draws the shared focus ring: an indigo border with a 2 px ring directly on the border.
- **Motion:** Colours fade quickly. Nothing moves.
- **Reduced motion:** There is no movement to remove, so reduced motion changes nothing. The colour change stays.

## Anatomy

- `Toggle`: A button that stays pressed or unpressed. Off is a white bordered button and on fills with the indigo tint, and it comes in several sizes, a rounded or pill shape and a neutral or indigo tone.
- `Icon`: An optional 16 px icon in front of the label, or alone when the toggle has an aria-label. It takes the label's colour.
- `Label`: The button's text. Keep it the same in both states, since the pressed attribute tells assistive technology which state it is in.
- `ToggleButton`: The bordered form of a toggle as an option in a Checkbox Button Group or Radio Button Group. In the checkbox group it stays a toggle with a checkbox square, in the radio group it becomes a radio.
- `Button Mark`

## Best practices

### Do

- Give an icon-only Toggle an aria-label such as Bold. The pressed attribute announces the state, not the label.
- Keep the label and icon the same in both states. A label that flips between Mute and Unmute makes a screen reader say the opposite of what the fill shows.
- Put related toggles in one bar with the toolbar role and an aria-label, and use one size and one tone in the row.
- Hold the state yourself when something else on the page depends on it, such as a filtered list.

### Don't

- Don't use a Toggle to run a one-off action such as Export. An action that doesn't stay on is a Button.
- Don't use separate Toggles for one choice among several, such as left, centre and right alignment. Use a Radio Button Group, which keeps exactly one option chosen and can't be cleared.
- Don't put a Toggle in a form to be submitted. Use a Checkbox or a Switch, which belong to the form and have a label beside them.

## API reference

### Toggle

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| defaultPressed | boolean | false | Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`. |
| disabled | boolean | false | Whether the component should ignore user interaction. |
| nativeButton | boolean | true | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| onPressedChange | ((pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void) |  | Callback fired when the pressed state is changed. |
| pressed | boolean |  | Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| shape | "rounded" \| "pill" | "rounded" | `rounded` gives the toggle 8 px corners and is the default; `pill` rounds it fully. |
| size | "default" \| "lg" \| "xl" \| "sm" \| "2xl" | "default" | The height of the toggle: `sm` is 32 px, `default` 36 px, `lg` 40 px, `xl` 44 px and `2xl` 48 px. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| tone | "indigo" \| "neutral" | "neutral" | `neutral` is white when off and tinted indigo when on. `indigo` is tinted at rest and takes the solid brand fill while it is pressed. |
| value | Value |  | A unique string that identifies the toggle when used inside a toggle group. |

Also accepts React.ButtonHTMLAttributes attributes.

### ToggleButton

| Prop | Type | Default | Description |
|---|---|---|---|
| className | string \| ((state: State) => string \| undefined) |  | CSS class applied to the element, or a function that returns a class based on the component's state. |
| defaultPressed | boolean | false | Whether the toggle button is currently pressed. This is the uncontrolled counterpart of `pressed`. |
| disabled | boolean | false | Whether the component should ignore user interaction. |
| indicator | boolean |  | Draws the radio circle or the checkbox square in front of the label. Default: on inside a RadioButtonGroup / CheckboxButtonGroup when the button has a text label, off for icon-only buttons (no text in children) and outside a group. Pass `f… |
| nativeButton | boolean | true | Whether the component renders a native `<button>` element when replacing it via the `render` prop. Set to `false` if the rendered element is not a button (for example, `<div>`). |
| onPressedChange | ((pressed: boolean, eventDetails: Toggle.ChangeEventDetails) => void) |  | Callback fired when the pressed state is changed. |
| pressed | boolean |  | Whether the toggle button is currently pressed. This is the controlled counterpart of `defaultPressed`. |
| render | React.ReactElement \| ComponentRenderFn<RenderFunctionProps, State> |  | Allows you to replace the component's HTML element with a different tag, or compose it with another component. Accepts a `ReactElement` or a function that returns the element to render. |
| style | React.CSSProperties \| ((state: State) => React.CSSProperties \| undefined) |  | Style applied to the element, or a function that returns a style object based on the component's state. |
| value | Value |  | A unique string that identifies the toggle when used inside a toggle group. |

Also accepts React.ButtonHTMLAttributes attributes.

## Examples

### Sizes: 32, 36, 40, 44 and 48 px

```tsx
import { Bold } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"

export function Example() {
  return (
    <Toggle>
      <Bold strokeWidth={1.5} />
      Bold
    </Toggle>
  )
}
```

### Content: an icon, a label, or both

```tsx
import { Bold } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"

export function Example() {
  return (
    <Toggle aria-label="Bold">
      <Bold strokeWidth={1.5} />
    </Toggle>
  )
}
```

### States: off, on and disabled

```tsx
import { Bold } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"

export function Example() {
  return (
    <Toggle>
      <Bold strokeWidth={1.5} />
      Bold
    </Toggle>
  )
}
```

### Control: uncontrolled or controlled

```tsx
import { Bold } from "lucide-react"
import { Toggle } from "@/components/ui/toggle"

export function Example() {
  return (
    <Toggle defaultPressed>
      <Bold strokeWidth={1.5} />
      Bold
    </Toggle>
  )
}
```

## In context

### Text formatting: four toggles in a bar

Each toggle switches one style on or off, and any mix can be on at once. The text under the bar follows them.

```tsx
import { Bold, Code, Italic, Underline } from "lucide-react"
import { useState } from "react"
import { Toggle } from "@/components/ui/toggle"

type FormatKey = "bold" | "italic" | "underline" | "code"

export function Example() {
  const [active, setActive] = useState<FormatKey[]>(["bold"])
  const set = (key: FormatKey, pressed: boolean) =>
    setActive(pressed ? [...active, key] : active.filter((item) => item !== key))
  const textClass = [
    active.includes("bold") && "font-bold",
    active.includes("italic") && "italic",
    active.includes("underline") && "underline",
    active.includes("code") && "font-mono",
  ]
    .filter(Boolean)
    .join(" ")

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <div role="toolbar" aria-label="Text formatting" className="flex w-fit gap-1 rounded-xl border border-border bg-card p-2">
        <Toggle size="sm" aria-label="Bold" pressed={active.includes("bold")} onPressedChange={(pressed) => set("bold", pressed)}>
          <Bold strokeWidth={1.5} />
        </Toggle>
        <Toggle size="sm" aria-label="Italic" pressed={active.includes("italic")} onPressedChange={(pressed) => set("italic", pressed)}>
          <Italic strokeWidth={1.5} />
        </Toggle>
        <Toggle size="sm" aria-label="Underline" pressed={active.includes("underline")} onPressedChange={(pressed) => set("underline", pressed)}>
          <Underline strokeWidth={1.5} />
        </Toggle>
        <Toggle size="sm" aria-label="Code" pressed={active.includes("code")} onPressedChange={(pressed) => set("code", pressed)}>
          <Code strokeWidth={1.5} />
        </Toggle>
      </div>
      <p className={textClass}>Focus on the three accounts that renew in October. Pull the usage reports before Thursday.</p>
    </div>
  )
}
```

### Inbox filters: toggles that narrow a list

A pressed toggle stays applied while people read. Pressing two narrows the list to messages that match both, and the count says how many are left.

```tsx
import { Mail, Paperclip, Star } from "lucide-react"
import { useState } from "react"
import { Toggle } from "@/components/ui/toggle"

type FilterKey = "unread" | "starred" | "attachment"

const MESSAGES = [
  { from: "Nora Lindgren", subject: "Q3 roadmap review", unread: true, starred: false, attachment: true },
  { from: "Daniel Okafor", subject: "Invoice INV-1048 approved", unread: false, starred: true, attachment: false },
  { from: "Priya Raman", subject: "Updated billing contacts", unread: true, starred: true, attachment: false },
  { from: "Tomás Ferreira", subject: "Brand guidelines, version 3", unread: false, starred: true, attachment: true },
  { from: "Maya Kessler", subject: "Research notes from Tuesday", unread: true, starred: false, attachment: false },
  { from: "Nora Lindgren", subject: "Your new workspace is ready", unread: false, starred: false, attachment: false },
]

export function Example() {
  const [active, setActive] = useState<FilterKey[]>([])
  const set = (key: FilterKey, pressed: boolean) =>
    setActive(pressed ? [...active, key] : active.filter((item) => item !== key))
  const shown = MESSAGES.filter((message) => active.every((key) => message[key]))

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <div role="group" aria-label="Filter messages" className="flex flex-wrap gap-2">
        <Toggle size="sm" pressed={active.includes("unread")} onPressedChange={(pressed) => set("unread", pressed)}>
          <Mail strokeWidth={1.5} />
          Unread
        </Toggle>
        <Toggle size="sm" pressed={active.includes("starred")} onPressedChange={(pressed) => set("starred", pressed)}>
          <Star strokeWidth={1.5} />
          Starred
        </Toggle>
        <Toggle size="sm" pressed={active.includes("attachment")} onPressedChange={(pressed) => set("attachment", pressed)}>
          <Paperclip strokeWidth={1.5} />
          Attachments
        </Toggle>
      </div>
      <p aria-live="polite" className="text-sm text-text-secondary">
        {shown.length} of {MESSAGES.length} messages
      </p>
      <ul className="flex flex-col divide-y divide-border">
        {shown.map((message) => (
          <li key={message.subject} className="flex flex-col py-2">
            <span className="text-sm font-medium text-foreground">{message.subject}</span>
            <span className="text-sm text-text-secondary">{message.from}</span>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

### Starred files: an icon toggle on every row

The star keeps its label and icon in both states, and the fill shows whether the file is starred. The label names the file, so the row reads Star Invoice INV-1048.pdf, pressed.

```tsx
import { Star } from "lucide-react"
import { useState } from "react"
import { Toggle } from "@/components/ui/toggle"

const FILES = [
  { name: "Q3 planning notes.md", meta: "Edited by Nora Lindgren" },
  { name: "Invoice INV-1048.pdf", meta: "Added by Daniel Okafor" },
  { name: "Brand guidelines.pdf", meta: "Added by Tomás Ferreira" },
  { name: "Roadmap 2027.xlsx", meta: "Edited by Priya Raman" },
]

export function Example() {
  const [starred, setStarred] = useState<string[]>(["Invoice INV-1048.pdf"])

  return (
    <div className="flex w-full max-w-md flex-col gap-3">
      <p aria-live="polite" className="text-sm text-text-secondary">
        {starred.length} starred
      </p>
      <ul className="flex flex-col divide-y divide-border">
        {FILES.map((file) => (
          <li key={file.name} className="flex items-center justify-between gap-4 py-2">
            <span className="flex min-w-0 flex-col">
              <span className="truncate text-sm font-medium text-foreground">{file.name}</span>
              <span className="truncate text-sm text-text-secondary">{file.meta}</span>
            </span>
            <Toggle
              size="sm"
              aria-label={`Star ${file.name}`}
              className="data-pressed:[&_svg]:fill-current"
              pressed={starred.includes(file.name)}
              onPressedChange={(pressed) => setStarred(pressed ? [...starred, file.name] : starred.filter((name) => name !== file.name))}
            >
              <Star strokeWidth={1.5} />
            </Toggle>
          </li>
        ))}
      </ul>
    </div>
  )
}
```

## For AI agents

`get_component("toggle")`

Hand your agent this page as Markdown or the WunderUI MCP server, not a screenshot.
