Toggle

A button that stays pressed: bold, pin, show grid.

Vibra transitions background, colour and shadow rather than all, and sets the sm size's label in the 13px register instead of 0.8rem; pressed is the kit's selected fill, --brand-muted, with the label in ink — not shadcn's muted plane, which measured 1.10:1 against the card and was the plane hover paints too. An unpressed toggle keeps its label in the quieter tier (muted-foreground) and the pointer gives it half the muted plane, so pressed and a hovered unpressed toggle sit 1.17:1 apart in the light and 1.21:1 in the dark (they were 1.11:1) and differ by the ink step in the label besides; a pressed toggle keeps its fill under the pointer, and a page's own hover:bg-* replaces the unpressed hover. Keyboard focus is the kit's focus-ring, the solid 2px accent outline Button and NavigationMenu wear, not shadcn's half-strength halo — and a toggle group's items, which are this toggle, carry it too.

Install

npx shadcn@latest add @vibra/toggle

Needs the @vibra registry in your components.json — set it up once.

Examples

import { Grid3x3Icon, PinIcon } from "lucide-react"

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

export default function ToggleDemo() {
  return (
    <div className="flex items-center gap-2">
      <Toggle variant="outline" aria-label="Show gridlines" defaultPressed>
        <Grid3x3Icon aria-hidden="true" />
      </Toggle>
      <Toggle variant="outline">
        <PinIcon data-icon="inline-start" aria-hidden="true" />
        Pin to overview
      </Toggle>
    </div>
  )
}

With text

Words alone, because the words are the setting, beside the figure they change.

Revenue in August

$26,116.61

73 orders, before refunds.

"use client"

import * as React from "react"

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

// Words alone, because the words are the setting. The figure it changes sits
// right beside it, so pressing it shows at once what it did.
export default function ToggleText() {
  const [net, setNet] = React.useState(false)

  return (
    <div className="flex w-full max-w-xs flex-col gap-2 rounded-xl bg-card p-4 ring-1 ring-border">
      <div className="flex items-center justify-between gap-3">
        <h3 className="type-eyebrow">Revenue in August</h3>
        <Toggle size="sm" variant="outline" pressed={net} onPressedChange={setNet}>
          Net of refunds
        </Toggle>
      </div>
      <p className="type-numeral text-3xl">{net ? "$25,759.63" : "$26,116.61"}</p>
      <p className="text-xs text-muted-foreground">
        {net ? "After $356.98 refunded on 3 orders." : "73 orders, before refunds."}
      </p>
    </div>
  )
}

With icon

Icon-only toggles over a table. aria-label names each one, and a tooltip shows the same words to the pointer and the keyboard.

"use client"

import { HighlighterIcon, SigmaIcon, WrapTextIcon } from "lucide-react"

import { Toggle } from "@/components/ui/toggle"
import { Tooltip, TooltipContent, TooltipTrigger } from "@/components/ui/tooltip"

const OPTIONS = [
  { label: "Wrap long text", icon: WrapTextIcon, pressed: false },
  { label: "Show a totals row", icon: SigmaIcon, pressed: true },
  { label: "Highlight overdue orders", icon: HighlighterIcon, pressed: false },
]

// Icon-only toggles over an orders table: aria-label names each for a screen
// reader, and the tooltip shows the same words to the pointer and the keyboard.
export default function ToggleIcon() {
  return (
    <div role="group" aria-label="Table view" className="flex items-center gap-1 rounded-lg bg-card p-1 ring-1 ring-border">
      {OPTIONS.map((option) => (
        <Tooltip key={option.label}>
          <TooltipTrigger render={<Toggle aria-label={option.label} defaultPressed={option.pressed} />}>
            <option.icon aria-hidden="true" />
          </TooltipTrigger>
          <TooltipContent>{option.label}</TooltipContent>
        </Tooltip>
      ))}
    </div>
  )
}

Pressed

A controlled toggle whose name never changes. aria-pressed carries the state, the star fills, and a status line says what it did.

Revenue by channel

Saved report · refreshed hourly

Pinned to the top of Reports in the sidebar.

"use client"

import * as React from "react"
import { StarIcon } from "lucide-react"

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

// The name stays "Favourite" and aria-pressed carries the state. Pressed shows
// in shape as well as on the selected fill: the star fills.
export default function TogglePressed() {
  const [favourite, setFavourite] = React.useState(true)

  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <div className="flex items-center justify-between gap-4">
        <div className="flex min-w-0 flex-col">
          <h3 className="truncate text-sm font-semibold">Revenue by channel</h3>
          <p className="text-xs text-muted-foreground">Saved report · refreshed hourly</p>
        </div>
        <Toggle variant="outline" pressed={favourite} onPressedChange={setFavourite}>
          <StarIcon data-icon="inline-start" aria-hidden="true" className="group-aria-pressed/toggle:fill-current" />
          Favourite
        </Toggle>
      </div>
      <p role="status" className="text-xs text-muted-foreground">
        {favourite ? "Pinned to the top of Reports in the sidebar." : "Back in the list with the other saved reports."}
      </p>
    </div>
  )
}

Disabled, with the reason

A disabled toggle leaves the tab order, so the reason is written beside it rather than hidden in a tooltip, and describes it.

Comparing needs a full year of orders. The store’s first came in on 9 March 2026.

import { CalendarRangeIcon, TrendingUpIcon } from "lucide-react"

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

// A disabled toggle leaves the tab order, so the reason cannot hide in a
// tooltip: it is written under the chart's options, where the eye goes when
// the dimmed one does nothing, and the toggle is described by it.
export default function ToggleDisabled() {
  return (
    <div className="flex w-full max-w-sm flex-col gap-2">
      <div role="group" aria-label="Revenue chart" className="flex flex-wrap items-center gap-2">
        <Toggle variant="outline" size="sm" defaultPressed>
          <TrendingUpIcon data-icon="inline-start" aria-hidden="true" />
          Trend line
        </Toggle>
        <Toggle variant="outline" size="sm" disabled aria-describedby="toggle-disabled-reason">
          <CalendarRangeIcon data-icon="inline-start" aria-hidden="true" />
          Compare to last year
        </Toggle>
      </div>
      <p id="toggle-disabled-reason" className="text-xs text-muted-foreground">
        Comparing needs a full year of orders. The store’s first came in on 9 March 2026.
      </p>
    </div>
  )
}

Formatting toolbar

Bold, italic, underline and strikethrough in one named multiple group. Tab enters once and the arrow keys move between them.

Invoice note

Payment is due within 30 days of the invoice date.

"use client"

import * as React from "react"
import { BoldIcon, ItalicIcon, StrikethroughIcon, UnderlineIcon } from "lucide-react"

import { cn } from "@/lib/utils"
import { ToggleGroup, ToggleGroupItem } from "@/components/ui/toggle-group"

const FORMATS = [
  { value: "bold", label: "Bold", icon: BoldIcon, style: "font-semibold" },
  { value: "italic", label: "Italic", icon: ItalicIcon, style: "italic" },
  { value: "underline", label: "Underline", icon: UnderlineIcon, style: "underline underline-offset-2" },
  { value: "strikethrough", label: "Strikethrough", icon: StrikethroughIcon, style: "line-through" },
]

// One named group, `multiple` because formats combine. Tab enters the group
// once, the arrow keys move between its items, and Space or Enter presses one.
export default function ToggleToolbar() {
  const [formats, setFormats] = React.useState<string[]>(["bold"])

  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <ToggleGroup
        multiple
        aria-label="Text formatting"
        variant="outline"
        spacing={0}
        value={formats}
        onValueChange={(next) => setFormats(next)}
      >
        {FORMATS.map((format) => (
          <ToggleGroupItem key={format.value} value={format.value} aria-label={format.label}>
            <format.icon aria-hidden="true" />
          </ToggleGroupItem>
        ))}
      </ToggleGroup>
      <figure className="flex flex-col gap-1.5">
        <figcaption className="type-eyebrow">Invoice note</figcaption>
        <p
          className={cn(
            "rounded-lg bg-card px-3 py-2 text-sm ring-1 ring-border",
            FORMATS.filter((format) => formats.includes(format.value)).map((format) => format.style)
          )}
        >
          Payment is due within 30 days of the invoice date.
        </p>
      </figure>
    </div>
  )
}

Filter chip

Toggles as filter chips. On, a chip takes the selected plane and a tick, and a status line gives the count and the total.

63 unpaid invoices, $219,087.30 in all.

"use client"

import * as React from "react"
import { CheckIcon } from "lucide-react"

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

// Northwind's 63 unpaid invoices, counted for each pair of filters.
const RESULTS: Record<string, string> = {
  "": "63 unpaid invoices, $219,087.30 in all.",
  overdue: "48 overdue invoices, $183,687.77 in all.",
  large: "27 unpaid invoices over $1,000, $209,004.05 in all.",
  "overdue large": "21 overdue invoices over $1,000, $176,724.05 in all.",
}

// A chip is a toggle: aria-pressed says it applies. On, it takes the selected
// plane and a tick, so the state never rests on colour alone.
const CHIP = "rounded-full aria-pressed:bg-brand-muted aria-pressed:text-foreground"
const CHECK = "hidden group-aria-pressed/toggle:block"

export default function ToggleFilterChip() {
  const [overdue, setOverdue] = React.useState(false)
  const [large, setLarge] = React.useState(false)
  const key = [overdue && "overdue", large && "large"].filter(Boolean).join(" ")

  return (
    <div className="flex w-full max-w-sm flex-col gap-3">
      <div role="group" aria-label="Filter unpaid invoices" className="flex flex-wrap gap-2">
        <Toggle variant="outline" size="sm" className={CHIP} pressed={overdue} onPressedChange={setOverdue}>
          <CheckIcon aria-hidden="true" className={CHECK} />
          Overdue
        </Toggle>
        <Toggle variant="outline" size="sm" className={CHIP} pressed={large} onPressedChange={setLarge}>
          <CheckIcon aria-hidden="true" className={CHECK} />
          Over $1,000
        </Toggle>
      </div>
      <p role="status" className="text-sm tabular-nums">
        {RESULTS[key]}
      </p>
    </div>
  )
}

Props

Prop	Type	Default	Description
variant	"default" \| "outline"	"default"	Bare, or bounded by the `--input` line.
size	"default" \| "sm" \| "lg"	"default"	32px tall by default; 28px or 36px.
pressed / defaultPressed	boolean	false	Whether it is pressed: controlled, or where it starts. It is announced through aria-pressed, so the label stays the same either way.
onPressedChange	(pressed: boolean) => void	—	Called with the new state on every press.
disabled	boolean	false	Dims it and takes it out of the tab order, so write the reason beside it and point aria-describedby at the words.

Dependencies

Registry

theme-vibra

npm

Source

components/ui/toggle.tsx

"use client"

import { Toggle as TogglePrimitive } from "@base-ui/react/toggle"
import { cva, type VariantProps } from "class-variance-authority"
import { cn } from "@/lib/utils"

const toggleVariants = cva(
  // The kit's one focus treatment, `focus-ring` — a solid 2px outline in the
  // accent, as on Button and NavigationMenu — in place of shadcn's 3px halo at
  // half strength, which measured 1.98:1 on white. Pressed is the kit's
  // selected fill, --brand-muted, with the label in ink; unpressed keeps its
  // label in the quieter tier, and the pointer gives it half the muted plane —
  // well short of the selected fill, so a hovered toggle never looks pressed.
  // Pressed is written after hover and outranks it, so a pressed toggle under
  // the pointer still reads as pressed, and a page's own `hover:bg-*` still
  // replaces the unpressed hover.
  "group/toggle inline-flex items-center justify-center gap-1 rounded-lg text-sm font-medium whitespace-nowrap text-muted-foreground transition-[background-color,color,box-shadow] focus-ring hover:bg-muted/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-destructive aria-pressed:bg-brand-muted aria-pressed:text-foreground [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
  {
    variants: {
      variant: {
        default: "bg-transparent",
        outline: "border border-input bg-transparent",
      },
      size: {
        default:
          "h-8 min-w-8 px-2.5 has-data-[icon=inline-end]:pe-2 has-data-[icon=inline-start]:ps-2",
        sm: "h-7 min-w-7 rounded-[min(var(--radius-md),12px)] px-2.5 text-label has-data-[icon=inline-end]:pe-1.5 has-data-[icon=inline-start]:ps-1.5 [&_svg:not([class*='size-'])]:size-3.5",
        lg: "h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pe-2 has-data-[icon=inline-start]:ps-2",
      },
    },
    defaultVariants: {
      variant: "default",
      size: "default",
    },
  }
)

function Toggle({
  className,
  variant = "default",
  size = "default",
  ...props
}: TogglePrimitive.Props & VariantProps<typeof toggleVariants>) {
  return (
    <TogglePrimitive
      data-slot="toggle"
      className={cn(toggleVariants({ variant, size, className }))}
      {...props}
    />
  )
}

export { Toggle, toggleVariants }