For the complete documentation index, see llms.txt. Markdown variants are available by appending .md to any URL or sending an Accept: text/markdown header. An agent skill is available at /.well-known/agent-skills/site-skill.md.
FrakmentFrakment

Toggle

A two-state button that can be toggled on or off.

toggle.tsx
"use client";

import { cva, type VariantProps } from "class-variance-authority";
import * as React from "react";
import { cn } from "@/lib/utils";

const toggleVariants = cva(
  "group/toggle hover:bg-muted hover:text-foreground focus-visible:border-ring focus-visible:ring-ring/50 aria-invalid:border-destructive aria-invalid:ring-destructive/20 aria-pressed:bg-muted data-[state=on]:bg-muted dark:aria-invalid:ring-destructive/40 inline-flex items-center justify-center gap-1 rounded-lg text-sm font-medium whitespace-nowrap transition-all outline-none focus-visible:ring-[3px] disabled:pointer-events-none disabled:opacity-50 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
  {
    defaultVariants: {
      size: "default",
      variant: "default",
    },
    variants: {
      size: {
        default:
          "h-8 min-w-8 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
        lg: "h-9 min-w-9 px-2.5 has-data-[icon=inline-end]:pr-2 has-data-[icon=inline-start]:pl-2",
        sm: "h-7 min-w-7 rounded-[min(var(--radius-md),12px)] px-2.5 text-[0.8rem] has-data-[icon=inline-end]:pr-1.5 has-data-[icon=inline-start]:pl-1.5 [&_svg:not([class*='size-'])]:size-3.5",
      },
      variant: {
        default: "bg-transparent",
        outline: "border-input hover:bg-muted border bg-transparent",
      },
    },
  }
);

type ToggleProps = Omit<
  React.ComponentPropsWithoutRef<"button">,
  "onChange" | "aria-pressed" | "type" | "ref"
> &
  VariantProps<typeof toggleVariants> & {
    as?: React.ElementType;
    asChild?: boolean;
    pressed?: boolean;
    defaultPressed?: boolean;
    onPressedChange?: (pressed: boolean) => void;
    ref?: React.Ref<HTMLButtonElement>;
  };

function Toggle({
  as,
  asChild,
  children,
  className,
  defaultPressed = false,
  onClick,
  onPressedChange,
  pressed: pressedProp,
  ref,
  size = "default",
  variant = "default",
  ...props
}: ToggleProps) {
  const isControlled = pressedProp !== undefined;
  const [uncontrolled, setUncontrolled] = React.useState(defaultPressed);
  const pressed = isControlled ? pressedProp : uncontrolled;
  const mergedClass = cn(toggleVariants({ className, size, variant }));

  const handleClick = (event: React.MouseEvent<HTMLElement>) => {
    onClick?.(event as never);
    if (event.defaultPrevented) {
      return;
    }
    const next = !pressed;
    if (!isControlled) {
      setUncontrolled(next);
    }
    onPressedChange?.(next);
  };

  if (asChild && React.isValidElement(children)) {
    const child = children as React.ReactElement<Record<string, unknown>>;
    return React.cloneElement(child, {
      ...props,
      "aria-pressed": pressed,
      className: cn(mergedClass, child.props.className as string),
      "data-slot": "toggle",
      "data-state": pressed ? "on" : "off",
      onClick: (event: React.MouseEvent<HTMLElement>) => {
        (
          child.props.onClick as
            | ((e: React.MouseEvent<HTMLElement>) => void)
            | undefined
        )?.(event);
        handleClick(event);
      },
      ref,
    } as never);
  }

  const Component = (as ?? "button") as React.ElementType;
  return (
    <Component
      {...props}
      aria-pressed={pressed}
      className={mergedClass}
      data-slot="toggle"
      data-state={pressed ? "on" : "off"}
      onClick={handleClick}
      ref={ref}
      {...(as ? {} : { type: "button" as const })}
    >
      {children}
    </Component>
  );
}

export { Toggle, toggleVariants };

Toggle is a two-state button rendered as a native <button> with aria-pressed. It supports default and outline variants, sm / default / lg sizes, and pressed / disabled states.

Installation

Usage

toggle.tsx
import { Toggle } from "@/components/ui/toggle";
<DocsBaseSwitcher base="web" component="toggle" className="mb-6" />
tsx
<Toggle aria-label="Toggle italic">
  <ItalicIcon />
  Italic
</Toggle>

Anatomy

tsx
<Toggle>
  <Icon />
  Label
</Toggle>
  • Toggle — native <button>; accepts variant, size, pressed, defaultPressed, onPressedChange, as
  • Icons and text are children; the pressed state styles icon fills via group-aria-pressed/toggle:

Examples

Outline

Pass variant="outline" for a bordered toggle.

toggle-outline.tsx
import { BoldIcon, ItalicIcon } from "lucide-react";
import { Toggle } from "@/components/ui/toggle";

export function ToggleOutline() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Toggle aria-label="Toggle italic" variant="outline">
        <ItalicIcon />
        Italic
      </Toggle>
      <Toggle aria-label="Toggle bold" variant="outline">
        <BoldIcon />
        Bold
      </Toggle>
    </div>
  );
}
tsx
<Toggle variant="outline" aria-label="Toggle italic">
  <ItalicIcon />
  Italic
</Toggle>

Text

Default variant — no border, transparent background.

toggle-text.tsx
import { ItalicIcon } from "lucide-react";
import { Toggle } from "@/components/ui/toggle";

export function ToggleText() {
  return (
    <Toggle aria-label="Toggle italic">
      <ItalicIcon />
      Italic
    </Toggle>
  );
}
tsx
<Toggle aria-label="Toggle italic">
  <ItalicIcon />
  Italic
</Toggle>

Sizes

size accepts sm, default, and lg.

toggle-sizes.tsx
import { Toggle } from "@/components/ui/toggle";

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

Disabled

Set disabled on the toggle to lock interaction.

toggle-disabled.tsx
import { Toggle } from "@/components/ui/toggle";

export function ToggleDisabled() {
  return (
    <div className="flex flex-wrap items-center gap-2">
      <Toggle aria-label="Toggle disabled" disabled>
        Disabled
      </Toggle>
      <Toggle aria-label="Toggle disabled outline" disabled variant="outline">
        Disabled
      </Toggle>
    </div>
  );
}
tsx
<Toggle disabled>Disabled</Toggle>
<Toggle variant="outline" disabled>Disabled</Toggle>

In Context

Toolbar toggle

toggle-toolbar.tsx
"use client";

import { BoldIcon } from "lucide-react";
import { Toggle } from "@/components/ui/toggle";

export function ToggleToolbar() {
  return (
    <Toggle aria-label="Bold" variant="outline">
      <BoldIcon />
    </Toggle>
  );
}

API Reference

Extends React.ComponentProps<"button">.

PropTypeDefaultDescription
variant
"default""outline"
—Visual style.
size
"sm""default""lg"
—Toggle size.
pressedboolean—Controlled pressed state.
defaultPressedboolean—Initial pressed state (uncontrolled).
onPressedChange(pressed: boolean) => void—Called when the pressed state changes.

Controlled

tsx
const [pressed, setPressed] = React.useState(false)
<Toggle pressed={pressed} onPressedChange={setPressed} />

States

StateHow
Offdefault
Onpressed prop
Disableddisabled prop

Keyboard

KeyAction
Space / EnterToggle

Data Attributes

AttributeValues
data-slottoggle
data-stateon | off
data-disabledtrue

Variants

VariantUse case
defaultSolid pressed state
outlineBordered, transparent until pressed

Accessibility

  • Toggle renders a button with aria-pressed.
  • Provide aria-label when the toggle is icon-only.
  • Keyboard: Space toggles.

Best Practices

  • Icon-only toggles need a label. aria-label is not optional.
  • Use ToggleGroup for multiple toggles. Standalone toggles read as buttons.
  • Persist the state. Toggles are stateful, not one-shot.