Toggle

A toggle is a two-state button that stays pressed when on. Use it for a single on/off control like bold, mute, or pin. For a set of mutually exclusive or multi-select toggles, use Toggle Group; for a labeled settings switch, use Switch.

Preview#

import { Toggle } from "@/components/ui/cubby-ui/toggle";
import { HugeiconsIcon } from "@hugeicons/react";
import { TextItalicIcon } from "@hugeicons/core-free-icons";
export default function ToggleBasic() {
  return (
    <Toggle aria-label="Toggle italic">

Installation#

npxnpx shadcn@latest add @cubby-ui/toggle

Usage#

import { Toggle } from "@/components/ui/cubby-ui/toggle";

<Toggle />

Examples#

Sizes#

Use size to set the toggle's height and padding.

import { Toggle } from "@/components/ui/cubby-ui/toggle";
import { HugeiconsIcon } from "@hugeicons/react";
import { TextBoldIcon } from "@hugeicons/core-free-icons";
export default function ToggleDifferentSizes() {
  return (
    <div className="flex items-center space-x-2">

With Text#

Put a text label beside the icon.

import { Toggle } from "@/components/ui/cubby-ui/toggle";
import { HugeiconsIcon } from "@hugeicons/react";
import { TextBoldIcon } from "@hugeicons/core-free-icons";
export default function ToggleWithText() {
  return (
    <Toggle>

Variants#

Use variant to set the toggle's fill.

"use client";
 
import { Toggle } from "@/components/ui/cubby-ui/toggle";
import { HugeiconsIcon } from "@hugeicons/react";
import { TextBoldIcon } from "@hugeicons/core-free-icons";
 

import { Toggle } from "@/components/ui/cubby-ui/toggle";
import { HugeiconsIcon } from "@hugeicons/react";
import { TextUnderlineIcon } from "@hugeicons/core-free-icons";
export default function ToggleOutlineVariant() {
  return (
    <Toggle variant="outline">

Custom Colors#

The toggle paints its fill from CSS variables, one per state:

Each variant sets them and the toggle picks one per state, so you recolor the fill by overriding them, with no hover: or data-pressed: prefixes. Override them rather than adding bg-* to the root: a root bg-* paints behind the fill layer, where opaque variants hide it. Set the label color with a state-prefixed text class:

<Toggle className="[--tgl-bg-selected:var(--color-violet-600)] data-pressed:text-white">
  <BoldIcon />
</Toggle>

Custom properties can't take Tailwind's /10 opacity shorthand; build a translucent tint with color-mix:

<Toggle className="[--tgl-bg-selected:color-mix(in_oklab,var(--primary)_10%,transparent)]">
  <BoldIcon />
</Toggle>

Any variable you don't override keeps the variant's color for that state.

The border lives on the toggle's paint pseudo-element, so before: classes restyle it, for example before:border-dashed or before:border-2. Only outline sets a visible --tgl-border, so on the other variants pair those classes with a color: [--tgl-border:var(--border)] before:border-dashed.

Controlled#

Use pressed and onPressedChange to drive the toggle state yourself.

"use client";
 
import { Toggle } from "@/components/ui/cubby-ui/toggle";
import { useState } from "react";
 
import { HugeiconsIcon } from "@hugeicons/react";

Disabled#

Set disabled to block interaction.

import { Toggle } from "@/components/ui/cubby-ui/toggle";
import { HugeiconsIcon } from "@hugeicons/react";
import { TextItalicIcon } from "@hugeicons/core-free-icons";
export default function ToggleDisabledState() {
  return (
    <Toggle disabled>

Accessibility#

Labels#

Give an icon-only toggle an aria-label that names what it controls, since it has no text for a screen reader to announce.

<Toggle aria-label="Toggle bold">
  <BoldIcon />
</Toggle>

API Reference#

The Toggle component is built on top of Base UI's Toggle. All Base UI props are supported. The documentation below only covers custom props and modified defaults specific to our implementation.

For the complete Base UI API, see the Base UI Toggle documentation.

Props#

Toggle#

A two-state button. Wraps Base UI's Toggle.

Upgrading#

If you're reinstalling over an earlier version, check these changes: