Components
Toggle
A button that turns a formatting option or view mode on or off. The selected state uses a soft accent fill.
Preview
import { Toggle } from "@/components/ui/toggle"
<Toggle>Pin item</Toggle>Usage
When to use
- Turn one option on or off, such as pinning an item or applying emphasis.
- Keep a toolbar action selected until the user turns it off.
When not to use
- An action with no persistent on state. Use Button.
- A setting submitted in a form. Use Switch.
- Related selection options. Use ToggleGroup.
Variants
variant
Transparent when off, or a surface with a neutral border for outline.
import { Toggle } from "@/components/ui/toggle"
<Toggle>Pin item</Toggle>
<Toggle variant="outline">Pin item</Toggle>size
Control height, text and icon size, the same steps as Button: sm 28px, md 32px (the default), lg 36px, xl 44px with a mouse; on touch md is 36px, lg 44px and xl 48px. Small controls keep a minimum hit area.
import { Toggle } from "@/components/ui/toggle"
<Toggle size="sm">Pin item</Toggle>
<Toggle>Pin item</Toggle>
<Toggle size="lg">Pin item</Toggle>
<Toggle size="xl">Pin item</Toggle>Examples
Formatting
import { Toggle } from "@/components/ui/toggle"
<Toggle>Bold</Toggle>Selected initially
import { Toggle } from "@/components/ui/toggle"
<Toggle variant="outline" defaultPressed>Grid view</Toggle>Icon only
import { IconBold } from "@tabler/icons-react"
import { Toggle } from "@/components/ui/toggle"
<Toggle iconOnly aria-label="Bold">
<IconBold size={16} />
</Toggle>Disabled selection
import { Toggle } from "@/components/ui/toggle"
<Toggle disabled defaultPressed>Locked format</Toggle>Do and don't
Do
- Use a stable label that names the option.
- Use iconOnly with aria-label for compact formatting controls.
Don't
- Do not use a Toggle for an action that has no persistent state.
- Do not use it for a setting that applies at once; use Switch.
Props
| Name | Type | Values | Default | Description |
|---|---|---|---|---|
| variant | enum | default | outline | default | Transparent when off, or a surface with a neutral border for outline. |
| size | enum | sm | md | lg | xl | md | Control height, text and icon size, the same steps as Button: sm 28px, md 32px (the default), lg 36px, xl 44px with a mouse; on touch md is 36px, lg 44px and xl 48px. Small controls keep a minimum hit area. |
| disabled | boolean | - | false | Prevents focus and selection and uses disabled colors. |
| iconOnly | boolean | - | false | Makes the button square. Requires aria-label on an icon-only button. |
| pressed | boolean | - | - | Controlled on or off state. Pair with onPressedChange. |
| defaultPressed | boolean | - | false | Initial state when uncontrolled. |
| onPressedChange | function | - | - | Receives the requested boolean state after activation. |
Anatomy
| Part | Description |
|---|---|
| root | The toggle button, transparent by default or a bordered surface in outline. On uses the soft accent pair. |
| icon | An optional decorative icon, 16px in sm, md and lg and 20px in xl. |
| hitArea | A transparent pseudo-element that extends the button target to size-target-min. |
Accessibility
Role: button
| Keys | Action |
|---|---|
| Space, Enter | Toggles pressed state. |
| Tab | Moves focus to the next control. |
- Text children provide the accessible name. iconOnly requires aria-label.
- aria-pressed exposes the on or off state. Keep the label stable when state changes.
- The button defaults to type="button" and does not submit its form.
- Pass size and weight to every icon. Use regular off and optionally fill on.
Install
npx shadcn add https://werewolf-ui.vercel.app/r/toggle.jsonThis also adds styles/werewolf.css, the tokens every component uses, and any other component it needs. Import that file once in your root CSS, after @import "tailwindcss", with a path relative to that CSS file (from app/globals.css it is @import "../styles/werewolf.css").