Toggle

A two-state button that can be either on or off. Perfect for binary options, formatting controls, and feature toggles in React applications with Next.js, TypeScript, and Tailwind CSS.

You know those buttons in text editors that stay pressed when you click them? Like bold, italic, or underline buttons that show whether formatting is active? Toggles give users that same clear visual feedback for any on/off option.

Basic toggle button

Simple bold formatting toggle:

Loading component...

Clean pressed/unpressed states with visual feedback. This free open source React component handles all the accessibility requirements and keyboard navigation for two-state controls.

npx shadcn@latest add toggle

Why toggles beat regular buttons

Toggles solve specific interaction problems:

State visibility - Users instantly see what's active
Persistent feedback - Button stays pressed while feature is on
Less cognitive load - No guessing about current state
Familiar pattern - Everyone knows how toggle buttons work
Space efficient - One button handles both on and off
Immediate response - Visual feedback happens instantly

Real-world toggle patterns

Text formatting group

Multiple toggles working together:

Loading component...

Complete editor toolbar with grouped toggles:

Loading component...

"use client"import { useState } from "react"import {   Bold,   Italic,   Underline,   AlignLeft,   AlignCenter,   AlignRight,  List,  ListOrdered,  Link} from "lucide-react"import { Toggle } from "@/components/ui/toggle"import { Separator } from "@/components/ui/separator"import { Card } from "@/components/ui/card"export default function ToggleToolbar() {  const [formatting, setFormatting] = useState({    bold: false,    italic: false,    underline: false,    list: false,    orderedList: false,    link: false,  })  const [alignment, setAlignment] = useState<'left' | 'center' | 'right'>('left')  const toggleFormat = (format: keyof typeof formatting) => {    setFormatting(prev => ({      ...prev,      [format]: !prev[format]    }))  }  const setAlign = (align: 'left' | 'center' | 'right') => {    setAlignment(align)  }  return (    <Card className="p-2 w-fit">      <div className="flex items-center gap-1">        {/* Text formatting */}        <div className="flex items-center gap-1">          <Toggle            pressed={formatting.bold}            onPressedChange={() => toggleFormat('bold')}            aria-label="Toggle bold"            size="sm"          >            <Bold className="h-4 w-4" />          </Toggle>          <Toggle            pressed={formatting.italic}            onPressedChange={() => toggleFormat('italic')}            aria-label="Toggle italic"            size="sm"          >            <Italic className="h-4 w-4" />          </Toggle>          <Toggle            pressed={formatting.underline}            onPressedChange={() => toggleFormat('underline')}            aria-label="Toggle underline"            size="sm"          >            <Underline className="h-4 w-4" />          </Toggle>        </div>        <Separator orientation="vertical" className="h-6" />        {/* Text alignment */}        <div className="flex items-center gap-1">          <Toggle            pressed={alignment === 'left'}            onPressedChange={() => setAlign('left')}            aria-label="Align left"            size="sm"          >            <AlignLeft className="h-4 w-4" />          </Toggle>          <Toggle            pressed={alignment === 'center'}            onPressedChange={() => setAlign('center')}            aria-label="Align center"            size="sm"          >            <AlignCenter className="h-4 w-4" />          </Toggle>          <Toggle            pressed={alignment === 'right'}            onPressedChange={() => setAlign('right')}            aria-label="Align right"            size="sm"          >            <AlignRight className="h-4 w-4" />          </Toggle>        </div>        <Separator orientation="vertical" className="h-6" />        {/* Lists and links */}        <div className="flex items-center gap-1">          <Toggle            pressed={formatting.list}            onPressedChange={() => toggleFormat('list')}            aria-label="Toggle bullet list"            size="sm"          >            <List className="h-4 w-4" />          </Toggle>          <Toggle            pressed={formatting.orderedList}            onPressedChange={() => toggleFormat('orderedList')}            aria-label="Toggle numbered list"            size="sm"          >            <ListOrdered className="h-4 w-4" />          </Toggle>          <Toggle            pressed={formatting.link}            onPressedChange={() => toggleFormat('link')}            aria-label="Insert link"            size="sm"          >            <Link className="h-4 w-4" />          </Toggle>        </div>      </div>    </Card>  )}

These examples show toggles in their natural habitat - toolbars, formatting controls, and settings where users need to toggle features on and off.

Perfect for binary controls

Toggles work best for features that have clear on/off states. Text formatting, view modes, filter options, feature flags, display settings. Much clearer than buttons that don't show their current state or switches that might be confusing in toolbar contexts.

Built on Radix UI Toggle primitive. Full TypeScript support. Styled with Tailwind CSS to match the shadcn design system.

API Reference

A two-state button component.

Prop	Type	Default	Description
`pressed`	`boolean`	-	The controlled pressed state of the toggle
`defaultPressed`	`boolean`	`false`	The default pressed state (uncontrolled)
`onPressedChange`	`(pressed: boolean) => void`	-	Event handler called when the pressed state changes
`disabled`	`boolean`	`false`	When true, prevents the user from interacting with the toggle
`variant`	`"default" \| "outline"`	`"default"`	The visual style variant
`size`	`"default" \| "sm" \| "lg"`	`"default"`	The size of the toggle
`className`	`string`	-	Additional CSS classes

Data Attributes

The toggle automatically applies data attributes for styling:

Attribute	Values	Description
`[data-state]`	`"on" \| "off"`	Indicates whether the toggle is pressed
`[data-disabled]`	Present when disabled	Applied when the toggle is disabled

Size Variants

Size	Description
`sm`	Smaller toggle for compact toolbars
`default`	Standard size for most use cases
`lg`	Larger toggle for primary actions

Style Variants

Variant	Description
`default`	Filled style with solid background when pressed
`outline`	Outlined style with border emphasis

"use client"import { useState } from "react"import {   Bold,   Italic,   Underline,   AlignLeft,   AlignCenter,   AlignRight,  List,  ListOrdered,  Link} from "lucide-react"import { Toggle } from "@/components/ui/toggle"import { Separator } from "@/components/ui/separator"import { Card } from "@/components/ui/card"export default function ToggleToolbar() {  const [formatting, setFormatting] = useState({    bold: false,    italic: false,    underline: false,    list: false,    orderedList: false,    link: false,  })  const [alignment, setAlignment] = useState<'left' | 'center' | 'right'>('left')  const toggleFormat = (format: keyof typeof formatting) => {    setFormatting(prev => ({      ...prev,      [format]: !prev[format]    }))  }  const setAlign = (align: 'left' | 'center' | 'right') => {    setAlignment(align)  }  return (    <Card className="p-2 w-fit">      <div className="flex items-center gap-1">        {/* Text formatting */}        <div className="flex items-center gap-1">          <Toggle            pressed={formatting.bold}            onPressedChange={() => toggleFormat('bold')}            aria-label="Toggle bold"            size="sm"          >            <Bold className="h-4 w-4" />          </Toggle>          <Toggle            pressed={formatting.italic}            onPressedChange={() => toggleFormat('italic')}            aria-label="Toggle italic"            size="sm"          >            <Italic className="h-4 w-4" />          </Toggle>          <Toggle            pressed={formatting.underline}            onPressedChange={() => toggleFormat('underline')}            aria-label="Toggle underline"            size="sm"          >            <Underline className="h-4 w-4" />          </Toggle>        </div>        <Separator orientation="vertical" className="h-6" />        {/* Text alignment */}        <div className="flex items-center gap-1">          <Toggle            pressed={alignment === 'left'}            onPressedChange={() => setAlign('left')}            aria-label="Align left"            size="sm"          >            <AlignLeft className="h-4 w-4" />          </Toggle>          <Toggle            pressed={alignment === 'center'}            onPressedChange={() => setAlign('center')}            aria-label="Align center"            size="sm"          >            <AlignCenter className="h-4 w-4" />          </Toggle>          <Toggle            pressed={alignment === 'right'}            onPressedChange={() => setAlign('right')}            aria-label="Align right"            size="sm"          >            <AlignRight className="h-4 w-4" />          </Toggle>        </div>        <Separator orientation="vertical" className="h-6" />        {/* Lists and links */}        <div className="flex items-center gap-1">          <Toggle            pressed={formatting.list}            onPressedChange={() => toggleFormat('list')}            aria-label="Toggle bullet list"            size="sm"          >            <List className="h-4 w-4" />          </Toggle>          <Toggle            pressed={formatting.orderedList}            onPressedChange={() => toggleFormat('orderedList')}            aria-label="Toggle numbered list"            size="sm"          >            <ListOrdered className="h-4 w-4" />          </Toggle>          <Toggle            pressed={formatting.link}            onPressedChange={() => toggleFormat('link')}            aria-label="Insert link"            size="sm"          >            <Link className="h-4 w-4" />          </Toggle>        </div>      </div>    </Card>  )}

The toggle supports full keyboard interaction:

Key	Description
`Space`	Activates/deactivates the toggle
`Enter`	Activates/deactivates the toggle

Accessibility Features

Built-in accessibility support includes:

ARIA attributes - Proper aria-pressed state communication
Keyboard support - Space and Enter keys toggle state
Focus management - Clear focus indicators
Screen reader support - State changes are announced
Semantic button - Uses proper button semantics
Label association - Connects with aria-label or external labels

Styling Examples

The toggle component supports different variants and sizes. Check the preview examples above to see various styling options in action, including outline variants, different sizes, and text labels.

Common use cases

Toggles work great for these scenarios:

Text formatting - Bold, italic, underline controls
View modes - List vs grid, expanded vs collapsed
Filter states - Show/hide categories, active filters
Feature flags - Enable/disable functionality
Layout options - Sidebar visibility, panel states
Tool selection - Active drawing tools, editing modes
Status indicators - Favorite, bookmark, follow states

Design guidelines

Keep these principles in mind when using toggles:

Clear labeling - Use aria-label or visible text
Visual distinction - Pressed state should be obvious
Group logically - Related toggles should be visually connected
Consistent sizing - Use same size within groups
Icon choice - Icons should clearly represent the action
State persistence - Toggle state should persist appropriately
Loading states - Show loading during async toggle operations
Error handling - Revert state if toggle action fails

Toggle

Basic toggle button

Why toggles beat regular buttons

Real-world toggle patterns

Text formatting group

Perfect for binary controls

API Reference

Toggle

Data Attributes

Size Variants

Style Variants

Usage Patterns

Controlled toggle

Toggle group state management

Keyboard Navigation

Accessibility Features

Styling Examples

Common use cases

Design guidelines

On this page

Toggle

Reacttoggle

Reacttoggle

Reacttoggle

Reactseparator

Reactcard

Reacttoggle

Reacttoggle

Reacttoggle

Reactseparator

Reactcard

On this page