Toggle

A button that stays pressed until it is clicked again.

import { BookmarkSimpleIcon } from "@phosphor-icons/react/dist/csr/BookmarkSimple"

import { Toggle } from "@/components/ui/toggle"

export default function ToggleDemo() {
  return (
    <Toggle aria-label="Toggle bookmark" size="sm" variant="outline">
      <BookmarkSimpleIcon aria-hidden="true" />
      Bookmark
    </Toggle>
  )
}

Installation

pnpm dlx shadcn@latest add @arene/toggle

Needs the arene setup first. Also adds Button.

Usage

import { Toggle } from "@/components/ui/toggle"

;<Toggle>Toggle</Toggle>

Use defaultPressed for an initial selection, or pressed and onPressedChange to control it. Give an icon-only toggle an aria-label.

RTL support is not included.

Outline

variant="outline" draws a border around the toggle.

import { HStack } from "@/components/ui/stack"
import { TextBIcon } from "@phosphor-icons/react/dist/csr/TextB"
import { TextItalicIcon } from "@phosphor-icons/react/dist/csr/TextItalic"

import { Toggle } from "@/components/ui/toggle"

export default function ToggleOutline() {
  return (
    <HStack wrap="wrap" align="center" gap={2}>
      <Toggle variant="outline" aria-label="Toggle italic">
        <TextItalicIcon aria-hidden="true" />
        Italic
      </Toggle>
      <Toggle variant="outline" aria-label="Toggle bold">
        <TextBIcon aria-hidden="true" />
        Bold
      </Toggle>
    </HStack>
  )
}

With text

Place text beside the icon to label the toggle.

import { TextItalicIcon } from "@phosphor-icons/react/dist/csr/TextItalic"

import { Toggle } from "@/components/ui/toggle"

export default function ToggleText() {
  return (
    <Toggle aria-label="Toggle italic">
      <TextItalicIcon aria-hidden="true" />
      Italic
    </Toggle>
  )
}

Size

Use size to change the height and minimum width.

import { HStack } from "@/components/ui/stack"
import { Toggle } from "@/components/ui/toggle"

export default function ToggleSizes() {
  return (
    <HStack wrap="wrap" align="center" gap={2}>
      <Toggle variant="outline" aria-label="Toggle small" size="sm">
        Small
      </Toggle>
      <Toggle variant="outline" aria-label="Toggle default" size="default">
        Default
      </Toggle>
      <Toggle variant="outline" aria-label="Toggle large" size="lg">
        Large
      </Toggle>
    </HStack>
  )
}

Disabled

Use disabled to prevent interaction.

import { HStack } from "@/components/ui/stack"
import { Toggle } from "@/components/ui/toggle"

export default function ToggleDisabled() {
  return (
    <HStack wrap="wrap" align="center" gap={2}>
      <Toggle aria-label="Toggle disabled" disabled>
        Disabled
      </Toggle>
      <Toggle variant="outline" aria-label="Toggle disabled outline" disabled>
        Disabled
      </Toggle>
    </HStack>
  )
}

API reference

Toggle accepts Base UI Toggle props, including render, plus xstyle, className and real inline style.

Toggle

PropTypeDefault
variant"default" | "outline""default"
size"sm" | "default" | "lg""default"

A surrounding ToggleGroup supplies variant and size when set on the group.

toggleStyles

KeyWhat it is
baseButton base paired with the shared focus ring
variantsDefault ghost and outline button styles
sizesButton heights and minimum widths
pressedThe flat fill and its text colour
pressedKeyThe raised key a pressed toggle is in a well
onWellRow-highlight hover for a ghost toggle on a well
pressedOnWellThe flat pill face a pressed toggle takes in a well
segmentCorner nested in a segmented group's well
disabledShared disabled opacity and pointer handling

ToggleGroupContext carries group-level variant and size to the toggle, and tells it when it sits in a well: a Toolbar or a segmented Toggle Group.

Data attributes

AttributeOnEffect
data-slot="toggle"buttonTargets the toggle
data-variant, data-sizebuttonMirror the resolved variant and size
data-pressed, data-disabledbuttonBase UI writes the current state