Toggle Button

A toggle button allows a user to toggle a selection on or off.

<ToggleButton>
  <PinIcon data-icon="inline-start" className="rotate-45" />
  Pin
</ToggleButton>

Installation

npm

pnpm

yarn

bun

pnpm dlx shadcn@latest add @dotui/toggle-button

Usage

A toggle button switches a selection on or off, like pinning or starring an item.

import { ToggleButton } from "@/components/ui/toggle-button"

<ToggleButton>Pin</ToggleButton>

Variants

Use the variant prop to set the visual style of the toggle button.

<ToggleButton variant="primary">Primary</ToggleButton>
<ToggleButton variant="secondary">Secondary</ToggleButton>
<ToggleButton variant="quiet">Quiet</ToggleButton>

Sizes

Use the size prop to set the size of the toggle button.

<ToggleButton size="xs">Extra small</ToggleButton>
<ToggleButton size="sm">Small</ToggleButton>
<ToggleButton size="md">Medium</ToggleButton>
<ToggleButton size="lg">Large</ToggleButton>

With icon

Add the data-icon="inline-start" or data-icon="inline-end" attribute to the icon for the correct spacing.

<ToggleButton>
  <PinIcon data-icon="inline-start" className="rotate-45" />
  Pin
</ToggleButton>
<ToggleButton>
  Pin
  <PinIcon data-icon="inline-end" className="rotate-45" />
</ToggleButton>

Icon buttons

Use the isIconOnly prop for icon-only toggle buttons.
Provide an aria-label to give the button an accessible name.

<ToggleButton isIconOnly aria-label="Pin">
  <PinIcon className="rotate-45" />
</ToggleButton>

Selection

Use defaultSelected to set the initial state, or isSelected with onChange to control it.

Pinned

<ToggleButton isSelected={isSelected} onChange={setSelected}>
  <PinIcon data-icon="inline-start" className="rotate-45" />
  Pin
</ToggleButton>
<span className="text-sm text-fg-muted">
  {isSelected ? "Pinned" : "Not pinned"}
</span>

API Reference

A toggle button allows a user to toggle a selection on or off, for example switching between two states or modes.

Prop	Type	Default
	`"primary" \| "quiet" \| "secondary"`	`'secondary'`
	`union`	`'md'`
	`boolean`	`—`
	`ReactNode \| function`	`—`
	`boolean`	`—`
	`Key`	`—`
	`boolean`	`—`
	`boolean`	`—`

	`function`	`—`

Last updated on 9/26/2026