Is the ai2 Toggle compatible with shadcn/ui?

Yes. It renders the same single Toggle component, exports the same toggleVariants helper and installs through the standard shadcn registry format, so it drops into any shadcn/ui project and existing snippets keep working.

Is the toggle accessible?

Yes. It is built on the radix-ui Toggle primitive, which renders a native button with the aria-pressed attribute reflecting the state, plus standard keyboard activation with Enter and Space. Give icon-only toggles an aria-label.

How do I install the ai2 Toggle?

Run npx shadcn add @ai2/toggle with the ai2 registry configured in components.json. An MCP agent can run the same install for you, or you can copy the source from this page manually.

Can an AI agent install and use this component?

Yes. The registry item ships agent-readable metadata and a working example, and the page provides a copy prompt. Point the shadcn MCP server at the @ai2 registry and the agent can search, inspect and install it on its own.

What variants, sizes and tones does it support?

Two variants (default and outline), three sizes (sm, md, lg) and two tones (neutral, brand), defined in a class-variance-authority matrix. The default is variant="default" size="md" tone="neutral".

What is the difference between Toggle, Switch and Checkbox?

Toggle is a pressed-state button for in-context modes like Bold. Switch is for settings that apply immediately, and Checkbox is a form input that gets submitted. All three exist in the ai2 registry; pick by semantics, not looks.

Does it work in controlled mode?

Yes. Pass pressed and onPressedChange to control the state from React, or use defaultPressed and let the radix primitive manage itself.

How is the pressed state styled?

The primitive sets data-state="on", which the component maps to the accent background and foreground tokens by default, or the brand-soft tokens with tone="brand", so the on state follows your theme in light and dark mode.

Can I customize the styling?

Fully. The source file lands in your project, styling is plain Tailwind CSS on top of the ai2 token file, and the element exposes data-slot and data-state attributes for targeted overrides. The exported toggleVariants helper reuses the exact styles elsewhere.

Toggle

A button that toggles between pressed and unpressed - the pressed state maps to the accent token.

formactions

A free styled version is available

import { Bold, Italic } from "lucide-react"

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

export default function ToggleDemo() {
  return (
    <div className="flex items-center gap-3">
      <Toggle aria-label="Toggle bold">
        <Bold />
      </Toggle>
      <Toggle tone="brand" defaultPressed aria-label="Toggle italic">
        <Italic />
      </Toggle>
    </div>
  )
}

Installation

Run the following command

npx shadcn@latest add @ai2/toggle

Dependencies, the @ai2/tokens theme and the component file are installed together.

Install dependencies

npm install class-variance-authority@^0.7.1 radix-ui@^1.6.1

Add the cn util

lib/utils.ts

import { clsx, type ClassValue } from "clsx"
import { twMerge } from "tailwind-merge"

export function cn(...inputs: ClassValue[]) {
  return twMerge(clsx(inputs))
}

/* Adds a source-attribution ref param to a URL (the inspiration exports mark their
   outbound links with an ai2.design attribution). An invalid URL is returned as is.

   This file is SHOWN TO THE CONSUMER: the docs component pages render the source of
   `cn` in a code block, so a Turkish comment here would reach every one of those
   pages. Keep it English. */
export function withRef(url: string, ref = "ai2.design"): string {
  try {
    const u = new URL(url)
    u.searchParams.set("ref", ref)
    return u.toString()
  } catch {
    return url
  }
}

Copy the source code

components/ui/toggle.tsx

"use client"

import type * as React from "react"
import { Toggle as TogglePrimitive } from "@/components/ui/primitives"
import { cva, type VariantProps } from "class-variance-authority"

import { cn } from "@/lib/utils"

const toggleVariants = cva(
  "inline-flex items-center justify-center gap-2 whitespace-nowrap rounded-lg text-sm font-medium outline-none transition-colors duration-(--motion-fast) hover:bg-surface-3 hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 disabled:pointer-events-none disabled:opacity-50 aria-invalid:border-danger aria-invalid:ring-danger/20 dark:aria-invalid:ring-danger/40 [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4 [&_i]:pointer-events-none [&_i]:shrink-0 [&_i]:text-base [&_i]:leading-none",
  {
    variants: {
      variant: {
        default: "bg-transparent text-muted-foreground",
        outline: "border border-field-border bg-transparent text-muted-foreground shadow-xs",
      },
      size: {
        sm: "h-8 min-w-8 px-1.5",
        md: "h-9 min-w-9 px-2",
        lg: "h-10 min-w-10 px-2.5",
      },
      tone: {
        neutral: "data-[state=on]:bg-accent data-[state=on]:text-accent-foreground",
        brand:
          "data-[state=on]:bg-brand-soft data-[state=on]:text-brand-soft-foreground",
      },
    },
    defaultVariants: { variant: "default", size: "md", tone: "neutral" },
  }
)

interface ToggleProps
  extends React.ComponentProps<typeof TogglePrimitive.Root>,
    VariantProps<typeof toggleVariants> {}

function Toggle({ className, variant, size, tone, ...props }: ToggleProps) {
  return (
    <TogglePrimitive.Root
      data-slot="toggle"
      data-tone={tone ?? "neutral"}
      className={cn(toggleVariants({ variant, size, tone, className }))}
      {...props}
    />
  )
}

export { Toggle, toggleVariants, type ToggleProps }

Manual installs skip the @ai2/tokens theme - add the token CSS from the theming guide or the tone colors will be missing.

Usage

import { Bold } from "lucide-react"

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

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

Icon-only toggles need an aria-label. For a set of related toggles, use Toggle Group instead.

Examples

Variants

Sizes

Tones

tone colors the pressed state: neutral uses the accent token, brand uses the brand-soft token.

With text and states

defaultPressed starts the toggle in its pressed state; pair pressed with onPressedChange for controlled usage.

Props

Toggle also accepts every radix Toggle prop - pressed, defaultPressed and onPressedChange included, plus native <button> props.

Prop	Type	Default	Description
`variant`	`"default" \| "outline"`	`"default"`	Visual style: transparent by default, or with an input border and shadow.
`size`	`"sm" \| "md" \| "lg"`	`"md"`	Height, minimum width and padding.
`tone`	`"neutral" \| "brand"`	`"neutral"`	Pressed-state color: neutral maps to the accent token, brand to the brand-soft token.

ai2 Toggle: a pressed-state button for React toolbars

The ai2 Toggle is a shadcn-compatible toggle button for React, built on the radix-ui Toggle primitive and styled with Tailwind CSS v4. It is a two-state button for on and off controls like Bold in a text editor, grid versus list in a file browser, or mute in a call bar. The pressed state maps to the accent token, so the on state follows your theme in both light and dark mode.

Because it ships through the shadcn registry format, you install it with one CLI command, an MCP agent, or a copy-paste, and the source lands in your own project. You own the file; there is no runtime dependency on ai2 itself. The live example above is the exact component you get.

What is the ai2 Toggle?

It is a single Toggle component with three style axes defined in a cva matrix: variant (default transparent, or outline with an input border and shadow) and size (sm, md, lg) and tone (neutral for an accent pressed state, brand for a brand-soft one). The anatomy matches shadcn/ui, so existing snippets and AI agents keep working without changes.

State is handled by the radix primitive: defaultPressed for uncontrolled usage, or pressed with onPressedChange when React state owns the value. The pressed visual reads from data-[state=on], styled with the accent token.

Why use it

Accessible by construction: The radix-ui Toggle primitive renders a real button with aria-pressed, so screen readers announce on and off correctly without any extra wiring.
Correct semantics for on/off: A toggle button is the right pattern when a control switches a mode in place, unlike a Checkbox (form input) or a Switch (settings on/off with immediate effect).
Two variants, three sizes, two tones: default stays transparent until hovered or pressed; outline carries an input border for toolbar rows. sm, md and lg cover dense toolbars to touch targets, and the brand tone recolors the pressed state.
Icon-ready sizing: Minimum widths per size keep icon-only toggles square, and unsized SVG children are normalized to size-4 automatically.
Agent-readable metadata: The registry item describes the variant and size axes and intended use in plain words, so an MCP agent can find, inspect and install it without guessing.

Features

shadcn registry install: One command adds the component, its dependencies and the @ai2/tokens theme to your project.
Controlled and uncontrolled state: Use defaultPressed for simple cases or pair pressed with onPressedChange when other UI depends on the state.
Token-driven pressed state: data-[state=on] maps to the accent background and foreground by default; tone="brand" swaps it for the brand-soft tokens, so the on state recolors with your theme instead of a hardcoded gray.
Focus-visible ring: A 3px ring appears on keyboard focus only, driven by the shared ring token.
Motion from tokens: The color transition reads --motion-fast from the shared token file, matching every other ai2 component.
Reusable toggleVariants export: The cva matrix is exported as toggleVariants, which is exactly what Toggle Group imports to keep group items visually identical.

Production tips

Label icon-only toggles: An icon-only toggle has no accessible name. Always set aria-label, like aria-label="Toggle bold", so screen readers announce what is being switched.
Do not use it as a Switch: For settings that read as on/off in a list, use the ai2 Switch. Reserve Toggle for in-context mode buttons like formatting controls.
Reach for Toggle Group for sets: Alignment pickers and view switchers are selection problems. Toggle Group handles single or multiple selection and keyboard focus across the set.
Keep the pressed state obvious: The accent background marks the on state. If you override colors, keep enough contrast between on and off; a toggle whose states look alike is worse than a plain button.
Prefer outline in crowded toolbars: On busy surfaces the default transparent variant can disappear. The outline variant keeps each control visible before interaction.

Works with the rest of ai2

The toggle is a toolbar citizen. Group related controls with the ai2 Toggle Group (which reuses this component's variants), separate clusters with an ai2 Separator, and explain icon-only controls with an ai2 Tooltip.

For one-shot actions next to your toggles, use the ai2 Button; for boolean settings in a form, the ai2 Switch is the better semantic fit. Everything shares one token source, so combinations stay visually consistent in both modes.