Docs › Components › Toggle

Shadcn Toggle

The shadcn/ui Toggle is a two-state button that shows a pressed or unpressed state, styled with Tailwind CSS v4. Built on accessible primitives, it is keyboard-operable and exposes its pressed state to assistive tech. Toggles power formatting and view controls across ShadcnStore blocks.

Key features

• Two-state (pressed/unpressed) button.
• Variants (default, outline) and sizes (sm, default, lg).
• Controlled or uncontrolled via pressed / defaultPressed.
• Keyboard operable, with pressed state exposed to assistive tech.
• Groups into a toolbar with Toggle Group.

Installation

npx shadcn@latest add toggle

Usage

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

export function Example() {
  return (
    <Toggle aria-label="Toggle bold">
      <Bold className="size-4" />
    </Toggle>
  )
}

Controlled state

const [pressed, setPressed] = useState(false)

<Toggle pressed={pressed} onPressedChange={setPressed} aria-label="Toggle bold">
  <Bold className="size-4" />
</Toggle>

With text

Pair an icon with a label for a clearer, more discoverable toggle.

import { Italic, Bold } from "lucide-react"

<Toggle variant="outline" aria-label="Toggle italic">
  <Italic />
  Italic
</Toggle>
<Toggle variant="outline" aria-label="Toggle bold">
  <Bold />
  Bold
</Toggle>

Variants and sizes

Set height and padding with the size prop: sm, default, or lg.

<Toggle variant="outline">Outline</Toggle>
<Toggle size="sm">Small</Toggle>
<Toggle size="lg">Large</Toggle>

Props

Prop	Type	Default	Description
pressed	boolean	—	Controlled pressed state.
defaultPressed	boolean	false	Uncontrolled initial state.
onPressedChange	(pressed) => void	—	Fires when toggled.
variant	default | outline	default	Visual style.
size	default | sm | lg	default	Control size.

Accessibility

• Give an icon-only toggle an aria-label describing what it toggles.
• The pressed state is exposed to assistive tech; do not fake it with a styled Button.
• For a set of related toggles, use Toggle Group so arrow keys move between them.

When to use the Toggle

Use a Toggle for a control that turns a formatting or view option on and off in place: bold, italic, grid vs. list, or a filter that stays active. For an immediate settings switch, use a Switch. For a one-shot action, use a Button.

Used in these blocks

• Apps: formatting and view toolbars.
• Datatables: view and density toggles.
• Widgets: chart view switches.

Related components

A Toggle is a two-state Button; for a settings on/off use a Switch, and for grouped toggles use Toggle Group. Pair icon toggles with a Tooltip for clarity.

FAQ

What is the shadcn toggle used for?

The Toggle is a two-state button for on/off controls like bold formatting or a view mode, often grouped in a toolbar.

What is the difference between Toggle and Switch?

Toggle is a button styled to show a pressed state, common in toolbars. Switch is a settings control styled like an on/off track.

How do I group toggles?

Use Toggle Group to build a set of related toggles with single or multiple selection, such as text alignment.

Why does my icon toggle have no accessible name?

An icon-only toggle needs an aria-label, since there is no visible text for screen readers to announce.