Forms

Toggle

A two-state button that can be toggled on or off, useful for formatting toolbars.

Preview

import { Toggle } from '@brika/clay/components/toggle';
import { Bold } from 'lucide-react';

/** A single toggle button that stays pressed until clicked again. */
export default function ToggleDefaultDemo() {
  return (
    <Toggle aria-label="Toggle bold">
      <Bold />
    </Toggle>
  );
}

01 Installation

Install

Pull Toggle from the barrel for everyday use, or the granular path when you want a tighter bundle.

tsxBarrel1 line

import { Toggle } from "@brika/clay";

tsxGranular1 line

import { Toggle } from "@brika/clay/components/toggle";

02 Usage

A minimal example

Drop this into a page. Native HTML attributes pass through to the underlying primitive.

tsxToggle.tsx11 lines

import { Toggle } from '@brika/clay/components/toggle';
import { Bold } from 'lucide-react';

/** A single toggle button that stays pressed until clicked again. */
export default function ToggleDefaultDemo() {
  return (
    <Toggle aria-label="Toggle bold">
      <Bold />
    </Toggle>
  );
}

03 Examples

Toggle, every way

Formatting

Multiple small icon toggles for a rich-text formatting toolbar.

GitHub

import { Toggle } from '@brika/clay/components/toggle';
import { Bold, Italic, Underline } from 'lucide-react';

/** Multiple small icon toggles for a rich-text formatting toolbar. */
export default function ToggleFormattingDemo() {
  return (
    <div className="flex gap-1">
      <Toggle size="sm" aria-label="Bold">
        <Bold />
      </Toggle>
      <Toggle size="sm" aria-label="Italic">
        <Italic />
      </Toggle>
      <Toggle size="sm" aria-label="Underline">
        <Underline />
      </Toggle>
    </div>
  );
}

Sizes

Three size presets side by side.

GitHub

import { Toggle } from '@brika/clay/components/toggle';
import { Bold } from 'lucide-react';

/** Three size presets side by side. */
export default function ToggleSizesDemo() {
  return (
    <div className="flex items-center gap-2">
      <Toggle size="sm" aria-label="Small bold">
        <Bold />
      </Toggle>
      <Toggle size="default" aria-label="Default bold">
        <Bold />
      </Toggle>
      <Toggle size="lg" aria-label="Large bold">
        <Bold />
      </Toggle>
    </div>
  );
}

Variants

Two variants: default (transparent background) and outline (bordered).

GitHub

import { Toggle } from '@brika/clay/components/toggle';
import { Bold, Italic } from 'lucide-react';

/** Two variants: default (transparent background) and outline (bordered). */
export default function ToggleVariantsDemo() {
  return (
    <div className="flex gap-2">
      <Toggle variant="default" aria-label="Default">
        <Bold />
        Default
      </Toggle>
      <Toggle variant="outline" aria-label="Outline">
        <Italic />
        Outline
      </Toggle>
    </div>
  );
}

04 Accessibility

Accessibility

Carries aria-pressed automatically, AT announces "pressed" / "not pressed".
Icon-only toggles REQUIRE an aria-label, there is no text fallback.
Use variant="outline" to make the active state more visually distinct.

05 Tokens 23 theme-overridable

Theme tokens

Every CSS variable Toggle reads, with its default and the dotted path you'd write in a ThemeConfig JSON to override it. Set any of these in your theme to retune Toggle without touching component code.

Toggle tokens

23 tokens

ColorFill, border, and text colors.7

--toggle-hover-containercolorvar(--muted)
components.toggle.hoverContainer
Hover background of the toggle in its resting (off) state. Pairs with `hover-label` and the hover backdrop blur.
--toggle-hover-labelcolorvar(--muted-foreground)
components.toggle.hoverLabel
Hover label color of the toggle in its resting (off) state.
--toggle-hover-bordercolorvar(--border)
components.toggle.hoverBorder
Hover border color of the toggle in its resting (off) state.
--toggle-active-containercolorvar(--accent)
components.toggle.activeContainer
Background of the toggle when pressed (`data-[state=on]`).
--toggle-active-labelcolorvar(--accent-foreground)
components.toggle.activeLabel
Label color of the toggle when pressed (`data-[state=on]`).
--toggle-active-bordercolorvar(--border)
components.toggle.activeBorder
Border color of the toggle when pressed (`data-[state=on]`).
--toggle-outline-bordercolorvar(--input)
components.toggle.outlineBorder
Resting border color of the outline toggle variant. Hover and active states fall through to `hover-border` / `active-border`.

GeometrySizes, lengths, and corner radii.5

--toggle-radiusradiusvar(--radius-control)
components.toggle.radius
Toggle corner radius.
--toggle-heightsize2.25rem
components.toggle.height
Default toggle height.
--toggle-padding-xsizecalc(var(--spacing) * 3)
components.toggle.paddingX
Inline padding inside the toggle.
--toggle-padding-ysizecalc(var(--spacing) * 2)
components.toggle.paddingY
Block padding inside the toggle.
--toggle-gapsizecalc(var(--spacing) * 2)
components.toggle.gap
Gap between adjacent children inside the toggle.

BorderBorder width and style.2

--toggle-border-widthborder-width0px
components.toggle.borderWidth
Border width on the toggle. Set non-zero for outline-style variants.
--toggle-border-styleborder-stylesolid
components.toggle.borderStyle
Border style on the toggle (`solid`, `dashed`, `double`, `none`).

TypographyTypeface, size, weight, spacing.6

--toggle-font-familyfont-familyvar(--font-sans)
components.toggle.fontFamily
Typeface for toggle.
--toggle-font-sizefont-sizevar(--text-body-md)
components.toggle.fontSize
Font size for toggle.
--toggle-font-weightfont-weight500
components.toggle.fontWeight
Font weight for toggle.
--toggle-line-heightline-height1.25
components.toggle.lineHeight
Line height for toggle.
--toggle-letter-spacingletter-spacing0
components.toggle.letterSpacing
Letter spacing for toggle. Useful for caps labels.
--toggle-text-transformtext-transformnone
components.toggle.textTransform
Text transform for toggle (`uppercase`, `lowercase`, `capitalize`, `none`).

ElevationDrop shadow and depth.1

--toggle-backdrop-blurblur0px
components.toggle.backdropBlur
Backdrop blur applied to the toggle on hover and active (`data-[state=on]`). Set non-zero for a frosted-glass affordance, the resting state stays transparent.

MotionAnimation duration and easing.2

--toggle-durationdurationvar(--motion-standard-duration)
components.toggle.duration
Transition duration for toggle state changes.
--toggle-easingeasingvar(--motion-standard-easing)
components.toggle.easing
Transition easing for toggle state changes.

Override in a theme

Authoring a theme is plain JSON. Drop overrides under components.toggle, the names are camelCase versions of the variable suffix.

jsonmy-theme.json12 lines

{
  "id": "my-theme",
  "name": "My Theme",
  "description": "...",
  "accentSwatches": ["#000"],

  "components": {
    "toggle": {
      "paddingX": "calc(var(--spacing) * 3)"
    }
  }
}

Then apply with applyTheme(myTheme) (see the theming guide), scope it to a subtree with themeToCssVars(myTheme, mode), or consume any token directly in your own JSX with the matching Tailwind utility (e.g. bg-toggle-…) — see the chips on each token row.

06 API reference

API reference

Props specific to Toggle. Native HTML attributes pass through to the underlying primitive, see the component source on GitHub for the full type signature.

sizedefault 'default'
'default' | 'sm' | 'lg' | 'icon'
Size preset: default, sm, lg, or icon.
variantdefault 'default'
'default' | 'outline'
Visual style: default (transparent) or outline (bordered).