Get Started
Components
- Accordion
- Attachment
- Avatar
- Badge
- Breadcrumb
- Button
- Button Group
- Card
- Checkbox
- Code Block
- Collapsible
- Dialog
- Dropdown Menu
- Empty
- Field
- Hover Card
- Input
- Input Group
- Input OTP
- Item
- Label
- Marker
- Message
- Number Flow
- Pagination
- Popover
- Progress
- Radio Group
- Select
- Slider
- Sonner
- Spinner
- Switch
- Tooltip
- Separator
- Sheet
- Tabs
- Textarea
- Toggle
- Toggle Group
- Trace
AI Elements
Libraries
Utilities
"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
$ bunx --bun frakment add toggle$ npx frakment add toggle$ pnpm dlx frakment add toggle$ yarn dlx frakment add toggle
Install the following dependencies:
$ bun add class-variance-authority$ npm install class-variance-authority$ pnpm add class-variance-authority$ yarn add class-variance-authority
Copy and paste the following code into your project.
"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 };Update the import paths to match your project setup.
Usage
import { Toggle } from "@/components/ui/toggle";
<DocsBaseSwitcher base="web" component="toggle" className="mb-6" /><Toggle aria-label="Toggle italic">
<ItalicIcon />
Italic
</Toggle>Anatomy
<Toggle>
<Icon />
Label
</Toggle>- Toggle — native
<button>; acceptsvariant,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.
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>
);
}<Toggle variant="outline" aria-label="Toggle italic">
<ItalicIcon />
Italic
</Toggle>Text
Default variant — no border, transparent background.
import { ItalicIcon } from "lucide-react";
import { Toggle } from "@/components/ui/toggle";
export function ToggleText() {
return (
<Toggle aria-label="Toggle italic">
<ItalicIcon />
Italic
</Toggle>
);
}<Toggle aria-label="Toggle italic">
<ItalicIcon />
Italic
</Toggle>Sizes
size accepts sm, default, and lg.
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>
);
}<Toggle size="sm">Small</Toggle>
<Toggle size="default">Default</Toggle>
<Toggle size="lg">Large</Toggle>Disabled
Set disabled on the toggle to lock interaction.
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>
);
}<Toggle disabled>Disabled</Toggle>
<Toggle variant="outline" disabled>Disabled</Toggle>In Context
Toolbar toggle
"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">.
| Prop | Type | Default | Description |
|---|---|---|---|
variant | "default""outline" | — | Visual style. |
size | "sm""default""lg" | — | Toggle size. |
pressed | boolean | — | Controlled pressed state. |
defaultPressed | boolean | — | Initial pressed state (uncontrolled). |
onPressedChange | (pressed: boolean) => void | — | Called when the pressed state changes. |
Controlled
const [pressed, setPressed] = React.useState(false)
<Toggle pressed={pressed} onPressedChange={setPressed} />States
| State | How |
|---|---|
| Off | default |
| On | pressed prop |
| Disabled | disabled prop |
Keyboard
| Key | Action |
|---|---|
Space / Enter | Toggle |
Data Attributes
| Attribute | Values |
|---|---|
data-slot | toggle |
data-state | on | off |
data-disabled | true |
Variants
| Variant | Use case |
|---|---|
default | Solid pressed state |
outline | Bordered, transparent until pressed |
Accessibility
Togglerenders a button witharia-pressed.- Provide
aria-labelwhen the toggle is icon-only. - Keyboard: Space toggles.
Best Practices
- Icon-only toggles need a label.
aria-labelis not optional. - Use
ToggleGroupfor multiple toggles. Standalone toggles read as buttons. - Persist the state. Toggles are stateful, not one-shot.
Related Components
- Toggle Group — set of toggles
- Switch — boolean setting