Toggle

A two-state button (pressed / not-pressed) and a grouped form thereof (mutually-exclusive or multi-select). Wraps @base-ui/react/toggle and @base-ui/react/toggle-group; we own the surface (size, variant, focus ring) and Base UI owns the pressed-state…

form & inputclient≥ 320pxuiv1.0.0

Toggle — live renderprimitives-toggle--sizes ↗

Rendered from the story the storybook (a11y) CI gate runs axe against — the preview can't show something that hasn't been verified.

Install

Two equivalent paths — the URL works in any shadcn-CLI setup; the alias works once you've registered @interlace in your components.json.

Via shadcn URL

npx shadcn@latest add https://ds.interlace.tools/r/toggle.json

With the @interlace alias

npx shadcn@latest add @interlace/toggle

Behavior

What this component does — the keyboard path, the measured colour, the text equivalent and the states it can be in. Every figure below is read out of the test or the source that enforces it by scripts/build-behavior-map.mjs, so nothing here can outlive the gate that keeps it true.

Measured contrast

packages/ui/__tests__/theme-contract-lock.test.ts ↗

Every semantic colour pair this component's own source uses, measured against the shipped hexes in all 4 theme × scheme combinations. The tightest is muted-foreground on muted at 7.34:1 (harbor · light), against a floor of 4.5:1.

Measured WCAG contrast ratios per token pair and theme
Pair	interlacelight	interlacedark	harborlight	harbordark	Floor
muted-foreground on mutedcopy on a muted surface	8.81:1	10.48:1	7.34:1	8.64:1	4.5:1SC 1.4.3
muted-foreground on backgroundsecondary copy	9.41:1	11.32:1	7.82:1	9.52:1	4.5:1SC 1.4.3
muted-foreground on cardsecondary copy in a card	9.41:1	10.48:1	8.25:1	8.64:1	4.5:1SC 1.4.3
ring on backgroundfocus ring (SC 2.4.13)	8.80:1	11.79:1	8.39:1	10.03:1	3.0:1SC 1.4.11
ring on cardfocus ring inside a card	8.80:1	10.92:1	8.86:1	9.10:1	3.0:1SC 1.4.11
accent-foreground on accenthover/highlight face	8.98:1	10.46:1	8.95:1	9.65:1	4.5:1SC 1.4.3

Text pairs are held to 4.5:1 (WCAG 2.2 SC 1.4.3); borders, rings and chart axes to 3:1 (SC 1.4.11 non-text). Bold is the worst cell in the row — the one a brand fork has to keep an eye on.

Runtime contract

packages/ui/vitest.config.ts ↗

Where it renders, how narrow it survives, and whether its lines are inside the coverage gate — three answers a consumer needs before the paste, not after the bug.

Render boundary: 'use client'
Hydrates. It brings JavaScript to any route that imports it — put the boundary here, not at the page.
Minimum viewport: MIN_VIEWPORT = 320
Declared, not assumed. Below 320 CSS px the preflight contract draws a dev-mode outline — how to switch it on.
Coverage gate: not in the gate
The 100% gate currently covers src/charts/**/*.{ts,tsx} and src/lib/**/*.{ts,tsx} and src/primitives/{button-variants,data-state-model,meter-scale,skeleton-variants}.ts and src/primitives/{alert,aspect-ratio,avatar,badge,box,breadcrumb,button,callout,card,checkbox,container,data-state,focus-ring,grade-badge,grid,input,label,meter,pagination,published-date,reading-time,section,section-boundary,separator,skip-link,stack,stat-strip,tag,textarea,typography,visually-hidden}.tsx. This file is outside it — the glob widens in phase 7.2.

History

This component is at v1.0.0, first shipped in @interlace/ui 1.0.0. The version is stamped as a banner into the file the install writes, so the copy in your tree says which one you have — compare it with the number above before deciding whether to re-run the install.

No release note names this component yet. It shipped with the release above and has not changed since — see the full changelog for what moved elsewhere in the DS.

Import

4 named exports — pull the parts you need.

Public API

import { MIN_VIEWPORT, Toggle, ToggleGroup, toggleVariants } from '@/components/ui/toggle';

Anatomy

Extracted from the primitive's JSDoc header. The source is the only documentation that can't drift.

Toggle                           (button — data-min-viewport=320)
    └─ children                    (icon / text)
  ToggleGroup                      (div — data-min-viewport=320, role=group or radiogroup)
    ├─ ToggleGroupItem
    ├─ ToggleGroupItem
    └─ ToggleGroupItem

Variants

Closed prop unions enforced by class-variance-authority. See Storybook's Variants story for the rendered matrix.

variant
- defaultdefault
- outline
size
- sm
- mddefault
- lg

API reference

Parsed from the type declarations in the source — the same file the install writes into your tree, so this table can't drift from the component you get.

ToggleProps

Plus the variant props listed above.No props of its own.

Accessibility

Every story for this component is rendered headlessly and checked with axe-core (wcag2aa, wcag22aa, best-practice, ACT) on every PR. That gate has no continue-on-error, so what ships has zero known violations.

What follows is what static analysis can see. Axe cannot press a key and never sees an overlay open, so the operable-without-a-mouse claim lives in Behavior instead, where the keyboard path is replayed step by step.

Focus + keyboard behaviour: Owned by @base-ui/react/toggle — focus trapping, dismissal and typeahead come from the headless primitive, not from us.
Focus ring (WCAG 2.2 SC 2.4.13): Inherited from the preflight focus contract shipped in @interlace/theme.
Reduced motion: No animation to gate.
ARIA in the source: role="group"
role="toolbar"
aria-orientation

Examples

3 more states from the same story file.

defaultprimitives-toggle--default ↗

outlineprimitives-toggle--outline ↗

groupprimitives-toggle--group ↗

R-rule compliance

Every primitive in @interlace/ui models to the portable 26-rule floor enforced by the componentApi ESLint preset. The cells below pin exactly where each rule applies in this file.

Rule	Concept	Where
R4	Extends Base UI part props	wrappers extend `React.ComponentProps<typeof BaseToggle/etc>`
R6	data-slot per part	toggle / toggle-group / toggle-group-item
R7	cva + cn + ...rest	`cn(toggleVariants({size,variant}), className)` + `{...props}`
R8	Enums for size / variant	size = sm
R12	Reuse over wrap	Base UI owns pressed state + ARIA
R14	Declares min viewport	`data-min-viewport={String(MIN_VIEWPORT)}` + exported const
R19	Tokens only	bg-muted, bg-accent, text-foreground — semantic tokens
R25	Client component	Required — Base UI Toggle ships client hooks
R26	A11y from upstream	role=button + aria-pressed handled by Base UI

Minimum viewport

This primitive declares MIN_VIEWPORT = 320 CSS px (DESIGN_PRINCIPLES #14). When mounted in a container narrower than this, the preflight contract draws a dev-mode outline so the regression is visible during local development.

Opt-in to the dev-mode warning

<body data-interlace-dev>...</body>

Add the data-interlace-dev attribute to the body in development builds only — preflight then outlines any primitive whose container is below its declared data-min-viewport.

Dependencies

Base UI primitive: @base-ui/react/toggle
Lucide icons: none
NPM dependencies: @base-ui/react
class-variance-authority
Registry dependencies: @interlace/theme
@interlace/cn

Source

The full implementation — components/ui/toggle.tsx once installed.

124 lines · TypeScript

github ↗

'use client';

import * as React from 'react';

// @interlace/toggle v1.0.0 — Interlace design system.
// Docs, props and live preview: https://ds.interlace.tools/c/toggle
// What changed since: https://ds.interlace.tools/c/toggle#history
// Generated banner — keep it, the upgrade diff reads this version.

/**
 * @interlace/ui — Toggle + ToggleGroup
 *
 * A two-state button (pressed / not-pressed) and a grouped form thereof
 * (mutually-exclusive or multi-select). Wraps @base-ui/react/toggle and
 * @base-ui/react/toggle-group; we own the surface (size, variant, focus
 * ring) and Base UI owns the pressed-state machinery + ARIA.
 *
 * ## Anatomy
 *
 *   Toggle                           (button — data-min-viewport=320)

…104 more lines…

Registry JSON

The raw registry record — what the shadcn CLI fetches.

/r/toggle.json