Toggle

A pressable on/off button for binary states like bold, italic, mute, or favorite. Built on Radix UI Toggle.

Overview

The Toggle component is a pressable on/off button for binary toggleable actions. Distinct from Switch — Toggle acts like a button that stays pressed (e.g. bold, italic, mute), while Switch is a sliding track for settings/preferences. Built on Radix UI's Toggle primitive for full accessibility.

Installation

Install the component via the CLI in one command.

npx @work-rjkashyap/unified-ui add toggle

pnpm dlx @work-rjkashyap/unified-ui add toggle

npx @work-rjkashyap/unified-ui add toggle

bunx @work-rjkashyap/unified-ui add toggle

If you haven't initialized your project yet, run npx @work-rjkashyap/unified-ui init first. See the CLI docs for details.

Or install the full package

Use this approach if you prefer to install the entire design system as a dependency instead of copying individual components.

npm install @work-rjkashyap/unified-ui

pnpm add @work-rjkashyap/unified-ui

yarn add @work-rjkashyap/unified-ui

bun add @work-rjkashyap/unified-ui

Anatomy

import { Toggle } from "@work-rjkashyap/unified-ui";

Examples

Basic Usage

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

<Toggle aria-label="Toggle bold">
<Bold className="size-4" />
</Toggle>
<Toggle aria-label="Toggle italic">
<Italic className="size-4" />
</Toggle>
<Toggle aria-label="Toggle underline">
<Underline className="size-4" />
</Toggle>

import { Bold, Italic, Underline } from "lucide-react";<Toggle aria-label="Toggle bold"><Bold className="size-4" /></Toggle><Toggle aria-label="Toggle italic"><Italic className="size-4" /></Toggle><Toggle aria-label="Toggle underline"><Underline className="size-4" /></Toggle>

Variants

DefaultOutlineGhost

{/* Default — transparent bg, fills on press */}
<Toggle variant="default" aria-label="Default toggle">
<Star className="size-4" />
</Toggle>

{/* Outline — bordered with visible boundary */}
<Toggle variant="outline" aria-label="Outline toggle">
<Star className="size-4" />
</Toggle>

{/* Ghost — minimal visual weight */}
<Toggle variant="ghost" aria-label="Ghost toggle">
<Star className="size-4" />
</Toggle>

{/* Default — transparent bg, fills on press */}<Toggle variant="default" aria-label="Default toggle"><Star className="size-4" /></Toggle>{/* Outline — bordered with visible boundary */}<Toggle variant="outline" aria-label="Outline toggle"><Star className="size-4" /></Toggle>{/* Ghost — minimal visual weight */}<Toggle variant="ghost" aria-label="Ghost toggle"><Star className="size-4" /></Toggle>

Sizes

{/* Icon-only sizes */}
<Toggle variant="outline" size="sm" aria-label="Small">
<Bookmark className="size-3.5" />
</Toggle>
<Toggle variant="outline" size="md" aria-label="Medium">
<Bookmark className="size-4" />
</Toggle>
<Toggle variant="outline" size="lg" aria-label="Large">
<Bookmark className="size-4" />
</Toggle>

{/* With text label */}
<Toggle variant="outline" size="sm"><Bold className="size-3.5" />Bold</Toggle>
<Toggle variant="outline" size="md"><Bold className="size-4" />Bold</Toggle>
<Toggle variant="outline" size="lg"><Bold className="size-4" />Bold</Toggle>

{/* Icon-only sizes */}<Toggle variant="outline" size="sm" aria-label="Small"><Bookmark className="size-3.5" /></Toggle><Toggle variant="outline" size="md" aria-label="Medium"><Bookmark className="size-4" /></Toggle><Toggle variant="outline" size="lg" aria-label="Large"><Bookmark className="size-4" /></Toggle>{/* With text label */}<Toggle variant="outline" size="sm"><Bold className="size-3.5" />Bold</Toggle><Toggle variant="outline" size="md"><Bold className="size-4" />Bold</Toggle><Toggle variant="outline" size="lg"><Bold className="size-4" />Bold</Toggle>

Size	Height	Padding	Font Size
`sm`	32px	8px	12px
`md`	36px	12px	14px
`lg`	40px	16px	14px

With Text Labels

<Toggle variant="outline">
<Eye className="size-4" />
Preview
</Toggle>
<Toggle variant="outline">
<Pin className="size-4" />
Pin
</Toggle>
<Toggle variant="outline">
<Heart className="size-4" />
Favorite
</Toggle>

<Toggle variant="outline"><Eye className="size-4" />Preview</Toggle><Toggle variant="outline"><Pin className="size-4" />Pin</Toggle><Toggle variant="outline"><Heart className="size-4" />Favorite</Toggle>

With Icon Props

<Toggle variant="outline" iconLeft={<Volume2 className="size-4" />}>
Sound On
</Toggle>
<Toggle variant="outline" iconLeft={<Lock className="size-4" />}>
Locked
</Toggle>

<Toggle variant="outline" iconLeft={<Volume2 className="size-4" />}>Sound On</Toggle><Toggle variant="outline" iconLeft={<Lock className="size-4" />}>Locked</Toggle>

Default Pressed

{/* Starts pressed */}
<Toggle variant="outline" defaultPressed aria-label="Bookmarked">
<Bookmark className="size-4" />
</Toggle>

{/* Starts unpressed */}
<Toggle variant="outline" aria-label="Not bookmarked">
<Bookmark className="size-4" />
</Toggle>

{/* Starts pressed */}<Toggle variant="outline" defaultPressed aria-label="Bookmarked"><Bookmark className="size-4" /></Toggle>{/* Starts unpressed */}<Toggle variant="outline" aria-label="Not bookmarked"><Bookmark className="size-4" /></Toggle>

Disabled State

<Toggle variant="default" disabled aria-label="Disabled default">
<Star className="size-4" />
</Toggle>
<Toggle variant="outline" disabled aria-label="Disabled outline">
<Star className="size-4" />
</Toggle>
<Toggle variant="ghost" disabled aria-label="Disabled ghost">
<Star className="size-4" />
</Toggle>
<Toggle variant="outline" disabled defaultPressed aria-label="Disabled pressed">
<Bookmark className="size-4" />
</Toggle>

<Toggle variant="default" disabled aria-label="Disabled default"><Star className="size-4" /></Toggle><Toggle variant="outline" disabled aria-label="Disabled outline"><Star className="size-4" /></Toggle><Toggle variant="ghost" disabled aria-label="Disabled ghost"><Star className="size-4" /></Toggle><Toggle variant="outline" disabled defaultPressed aria-label="Disabled pressed"><Bookmark className="size-4" /></Toggle>

Props

Prop	Type	Default	Description
`variant`	`"default" \| "outline" \| "ghost"`	`"default"`	Visual variant of the toggle.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Size of the toggle.
`pressed`	`boolean`	—	Controlled pressed state.
`defaultPressed`	`boolean`	—	Default pressed state for uncontrolled usage.
`onPressedChange`	`(pressed: boolean) => void`	—	Callback fired when the pressed state changes.
`disabled`	`boolean`	`false`	Disables the toggle.
`iconLeft`	`ReactNode`	—	Icon rendered before the label.
`iconRight`	`ReactNode`	—	Icon rendered after the label.
`className`	`string`	—	Additional CSS classes.

Accessibility

Icon-only toggles must include an aria-label to be accessible to screen readers.

aria-pressed — Radix automatically manages the aria-pressed attribute based on the toggle state.
Keyboard — Space and Enter keys toggle the pressed state (handled by Radix).
Focus ring — Visible on keyboard navigation via focus-visible.
Disabled — Uses both the disabled attribute and Radix's data-disabled for styling.
Role — Renders as a <button> with implicit button role.

Toggle vs Switch

Feature	Toggle	Switch
Looks like	A button that stays pressed	A sliding track with thumb
Best for	Toolbar actions (bold, italic)	Settings and preferences
Groupable	Yes, via `ToggleGroup`	No
Label	Icon or text inside the button	Label beside the track

Design Tokens

Token	Usage
`--muted`	Hover background
`--secondary`	Pressed state background (default)
`--foreground`	Pressed state text color
`--muted-foreground`	Unpressed text color
`--border`	Outline variant border
`--border-strong`	Outline pressed border
`--radius-md`	Border radius
`--duration-fast`	Transition speed
`--easing-standard`	Easing curve

On this page