An open source design system that's fully customizable and agent ready
schema_version: 3 template_version: 7 kind: component id: component:ToggleButton authority: current archive_reason: null superseded_by: null approved_by: cixzhang approved_at: 2026-10-25 owners: [cixzhang] review_triggers: [public-api, behavior, layout, theming, accessibility] verified_by: [ packages/core/src/ToggleButton/ToggleButton.test.tsx, packages/core/src/ToggleButton/tests/ToggleButton.a11y.test.tsx, packages/core/src/ToggleButton/tests/ToggleButton.a11y.chromium.spec.ts, ] modules: [] families: [family:buttons] design_specs: [design:reduced-motion] architecture: [ architecture:component-style-authoring, architecture:component-theming-surface, architecture:public-component-api, ] contributing: []
system_specs: [spec:AST-085]
ToggleButton component contract
Contract at a glance
| Area | Contract |
|---|---|
| Public contract | None changes. ToggleButton takes label, isPressed, onPressedChange, pressedChangeAction, icon, pressedIcon, isIconOnly, children, size, elevation, isDisabled, isLoading, tooltip, and value. |
| Behavior | A ghost Button with aria-pressed. Standalone, it requests the next pressed value from the caller and may run an interruptible Action with an optimistic pressed state. As a valued ToggleButtonGroup member, the group owns both. |
| End-user impact | People see and hear whether a toggle is on. A pending toggle shows its new state at once and can be reversed by clicking again. The label does not shift width when pressed. A disabled toggle without a tooltip leaves the tab order. |
| Builder impact | None. |
| Compatibility/readiness | Records shipped behavior; no API, default, or DOM change. Native disabled without a tooltip conflicts with spec:AST-085 FR1 and FR4; Button's reduced-motion gaps apply; a pre-prevented click skips the Action; caller pressed attributes override ToggleButton's own; the label renders twice; consumer docs promise a tooltip that does not exist. All are listed under Current-state impact. |
| Review checks | Reject a toggle without aria-pressed, a caller onClick that replaces the toggle request, an Action that runs after a prevented callback, a re-click derived from a stale committed value, or pressed state that shifts outer size. |
| Governing rules | family:buttons FR1–FR11, AV1–AV4; component:Button; spec:AST-085 FR1, FR4; design:reduced-motion DR1, DR3; architecture:public-component-api INV5; architecture:component-style-authoring INV7. |
This table is a review projection; the body below is authoritative.
Intent
ToggleButton is the family's persistent-press control. It reuses Button's
surface and adds a controlled pressed state, pressed-state paint, an optional
pressed icon, and an interruptible pressed Action, as family:buttons
assigns. Consumer usage lives in ToggleButton.doc.mjs.
Compatibility and migration
- Released default preserved:
yes; unpressed,size="md",elevation="none" - Compatibility class: records shipped behavior; no public prop, default, export, or DOM change
- Controlled/uncontrolled behavior: controlled only.
isPressed(defaultfalse) is the committed value; ToggleButton holds no committed state of its own, only an optimistic value while an Action is pending - Migration decision: none
Consumer migration instructions belong in consumer docs and release notes.
Ownership boundary
Owns
- The effective pressed state,
aria-pressed, and the next-state request. - Callback, caller
onClick, and Action ordering for a standalone toggle. - The optimistic pressed value while an Action is pending.
- Pressed paint, the pressed icon swap, the pressed label weight, and a stable outer size while pressed.
- The
toggle-buttontarget and itsisPressedandelevationreflection. - How a valued member defers to its ToggleButtonGroup.
Does not own / non-goals
- The surface, naming rules, size heights, pending presentation, disabled
rendering, tooltip, link mode, and feedback — owned by
component:Button. - Group selection state, single or multiple mode, and group layout — owned by
component:ToggleButtonGroup. - On/off settings — owned by
component:Switch. - Inheriting an outer size provider — not provided (OQ1).
Public concepts
| Concept | Closed values or states | Meaning | Availability by variant/orientation/state | Default | Owner | Stability | Invalid-value behavior |
|---|---|---|---|---|---|---|---|
| Pressed | pressed, unpressed | The retained on/off state. | Standalone from isPressed; valued group members from the group. |
unpressed | component:ToggleButton |
Stable | Not applicable. |
| Pressed Action | absent, idle, pending | Async work run for a standalone toggle. | Standalone only; ignored for valued group members. | absent | component:ToggleButton |
Stable | Not applicable. |
| Pressed icon | caller node | The icon shown while pressed. | When pressed; falls back to icon. |
icon |
component:ToggleButton |
Stable | Not applicable. |
| Group value | string | Identifies the member to its ToggleButtonGroup. | Inside a ToggleButtonGroup. | none | component:ToggleButton |
Stable | Without value, a member behaves standalone. |
| Size | sm, md, lg |
Control height. | Always. | Group size, else md |
family:buttons |
Stable | TypeScript rejects other values. |
| Elevation | none, low, med, high |
Resting shadow depth. | Standalone and inside a ToggleButtonGroup. | none |
family:buttons |
Stable | TypeScript rejects other values. |
Behavioral and layout contract
| ID | Invariant | Basis |
|---|---|---|
| FR1 | ToggleButton renders one Button with the ghost variant and Button's interruptible pending mode, and sets aria-pressed to the effective pressed value. Other supplied props reach Button. |
family:buttons FR2, FR6, AV3; current source |
| FR2 | The effective pressed value is the group's selection for a valued member inside a ToggleButtonGroup, otherwise isPressed (default false); while a standalone Action is pending, the optimistic value replaces it. |
family:buttons FR6, FR11; current tests |
| FR3 | Standalone activation: a caller onClick runs first. If that onClick calls preventDefault(), nothing else runs. Otherwise onPressedChange(next, event) runs synchronously, where next is the inverse of the effective value. If it calls preventDefault(), the Action does not run. A click already prevented before the caller onClick ran still calls onPressedChange, and pressedChangeAction MUST then run (family:buttons FR5). Implementation gap: Button skips its clickAction for any click already prevented, so pressedChangeAction does not run and an Action-only toggle ignores that click. |
family:buttons FR5; current tests |
| FR4 | With pressedChangeAction, a standalone activation sets the optimistic value to next and runs the Action through Button's clickAction; the Button is pending until it settles. The Action runs with or without onPressedChange. A re-click while pending is accepted and derives next from the optimistic value. When it settles, the committed isPressed shows. |
family:buttons FR4–FR6; current tests |
| FR5 | Without pressedChangeAction, activation is synchronous and reports no pending state. |
family:buttons FR5; current tests |
| FR6 | A valued member inside a ToggleButtonGroup asks the group to toggle its value on every enabled activation, after any caller onClick and whether or not that onClick prevented default. It never calls its own onPressedChange or pressedChangeAction and never reports Action pending. |
family:buttons FR11; current tests |
| FR7 | Disabled when its own isDisabled or its group's isDisabled is true; an enabled group never re-enables a member that disables itself. A disabled toggle never requests a state change and follows component:Button FR10, including its implementation gap. |
family:buttons FR3; current tests |
| FR8 | While pressed, the surface paints the pressed overlay color; under forced colors it paints Highlight with HighlightText. The visible label renders semibold while pressed, and pressing MUST NOT change outer size. Content MUST render once, with no hidden twin to reserve width (architecture:component-style-authoring INV7). Implementation gap: a labelled toggle wraps its label in a span beside a hidden semibold copy that reserves the width, so the label renders twice and children mount twice. Icon-only toggles render no copy. |
family:buttons FR7, FR9; current source and tests; architecture:component-style-authoring INV7 |
| FR9 | While pressed and pressedIcon is supplied, the icon slot shows pressedIcon; otherwise it shows icon. |
family:buttons AV2; current tests |
| FR10 | Size is the explicit size, then the enclosing ToggleButtonGroup's size, then md; ToggleButton does not read an outer size provider. |
family:buttons FR7; current source |
| FR11 | elevation paints Button's shadow standalone and inside a ToggleButtonGroup. |
family:buttons FR8, FR12; current tests |
| FR12 | The root carries both astryx-button and astryx-toggle-button, reflects data-is-pressed as "true" or "false", and reflects data-elevation. A caller className is kept alongside them. A caller data-is-pressed MUST NOT replace the reflected value. Implementation gap: caller props spread last, so a caller aria-pressed or data-is-pressed overrides ToggleButton's own. |
family:buttons FR10; architecture:component-theming-surface; tests; architecture:public-component-api INV5 |
| FR13 | Visible content is children when supplied, else label; icon-only shows no visible text. When label is non-empty it is the accessible name, because Button sets it as aria-label (component:Button ORD4). |
family:buttons FR1; current tests |
| FR14 | Pending presentation and press feedback follow component:Button FR8 and FR15: ToggleButton is a standalone Button inside or outside a ToggleButtonGroup, so it takes the press scale, which MUST NOT apply under reduced motion (design:reduced-motion DR1), and its interruptible Spinner waits the medium delay and MUST appear at once under reduced motion with a fine pointer (DR3). Implementation gap: both the press scale and the Spinner fade still apply under reduced motion, and content that paints its own colors stays visible beside the Spinner. |
component:Button; design:reduced-motion; current source |
Allowed variation
- AV1 — Pressed paint. Themes may restyle the pressed state through
toggle-button[data-is-pressed="true"]; pressed must stay distinguishable from unpressed, including under forced colors. - AV2 — Icons. Any caller node may fill
iconandpressedIcon.
Representative states
| State | Required invariant | Allowed variation |
|---|---|---|
| Unpressed | aria-pressed="false"; ghost surface; regular weight. |
Icon. |
| Pressed | aria-pressed="true"; pressed paint; semibold label; same outer size. |
Pressed icon. |
| Action pending | Optimistic pressed value; Spinner and aria-busy; still operable. |
Spinner delay. |
| Valued group member | Pressed from the group; activation calls the group; no Action. | Elevation. |
| Disabled with tooltip | aria-disabled; focusable; no state request. |
— |
| Disabled, no tooltip | Focusable with aria-disabled; no state request. Implementation gap: native disabled (FR7). |
— |
Transformation and precedence order
- ORD1 — Effective pressed. Group selection for a valued member, then the
pending optimistic value, then
isPressed, thenfalse. - ORD2 — Standalone activation. Caller
onClick, thenonPressedChange, then the Action; a newly prevented event stops the steps after it. A click prevented before the calleronClickstill reachesonPressedChange(FR3 gap for the Action). - ORD3 — Disabled. Group disabled or own disabled; either is enough.
Performance and resources
- PR1 — Width reservation. A labelled toggle renders three elements where
its label text would do: a wrapper, the visible label, and a hidden copy;
with
childrenthe children subtree mounts twice. No measurement runs. This cost is the FR8 gap.
Accessibility contract
- AR1 — State.
aria-pressedMUST reflect the effective pressed value (FR2), including the optimistic value while pending, and a caller prop MUST NOT replace it (architecture:public-component-apiINV5). Implementation gap: caller props spread last, so a calleraria-pressedoverrides it. - AR2 — Name. A non-empty
labelis the accessible name (FR13); the width-reservation copy (FR8 gap) is hidden from assistive technology. - AR3 — Forced colors. The pressed state stays visible under forced colors (FR8), as WCAG 1.4.11 requires.
- AR4 — Visible hint. An icon-only toggle shows a tooltip only when the
caller sets
tooltip. - AR5 — Everything else. Keyboard, focus indicator, loading announcement,
busy and disabled exposure, and target size follow
component:ButtonAR2–AR6.
Design relationships
| Anatomy or state | Design requirement | Representation authority | Hierarchy role | Component contract |
|---|---|---|---|---|
| Icon | Leading icon; replaced by Pressed icon while pressed. | Current source and tests | Supporting | FR9 |
| Pressed icon | Alternate icon while pressed. | Current source and tests | Supporting | FR9 |
| Label | Visible text, semibold while pressed, at a stable width (FR8 gap: hidden copy). | Current source and tests | Prominent | FR8, FR13 |
| Spinner | Button's Spinner over hidden content while an Action runs. | Current source | Supporting | FR4 |
| Pressed surface | Pressed overlay fill; Highlight under forced colors. |
Current source and tests | Prominent | FR8 |
design:reduced-motion governs the inherited press scale and Spinner reveal
(FR14); no other design record governs ToggleButton. The root carries toggle-button (and
Button's button); Icon, Pressed icon, and Label take color from them, and the
Spinner is a Spinner instance. The consumer anatomy names no root part, so this
record carries no anatomy-theming map.
Family and system relationships
family:buttonsowns persistent-press semantics, callback and Action order, and group ownership of valued members (FR5, FR6, FR11); ToggleButton adopts them. The family's elevation axis is shipped on ToggleButton (FR11).component:Buttonowns the rendered surface and pending, disabled, and tooltip behavior.component:ToggleButtonGroupowns selection for valued members.spec:AST-085applies through Button; the gap is FR7 here.
Verification map
| Contract | Verification | Representative states | Mutation or failure expectation | Audit section |
|---|---|---|---|---|
| FR1, FR2, ORD1, AR1 | ToggleButton.test.tsx; ToggleButton.a11y.chromium.spec.ts standalone and group states |
Unpressed, pressed, icon-only, composed label | Missing or stale aria-pressed fails. |
audit:ToggleButton/accessibility |
| FR3–FR5, ORD2 | ToggleButton.test.tsx callback, Action, and caller-onClick suites |
Callback only, Action only, both, prevented, pending re-click | Order flips, a prevented callback still runs the Action, or callback-only reports pending fails. Evidence gap: no test runs pressedChangeAction on a click prevented before the toggle's handler. |
audit:ToggleButton/behavior |
| FR6 | ToggleButton.test.tsx group-ownership cases |
Member with standalone handlers; member with onClick |
A member that runs its own handler or skips the group toggle fails. | audit:ToggleButton/behavior |
| FR7, ORD3 | ToggleButton.test.tsx disabled suite; ToggleButton.a11y.test.tsx and ToggleButton.a11y.chromium.spec.ts disabled states |
Member and group disabled; tooltip-bearing disabled | A disabled toggle that toggles, or an enabled group re-enabling a member, fails. The shared disabled state expects native disabled, matching the FR7 gap. |
audit:ToggleButton/accessibility |
| FR8, FR9, AR3 | ToggleButton.test.tsx width-reservation, pressed-icon, and forced-colors cases |
Labelled and icon-only; pressed and unpressed | A wrong icon or no forced-colors pressed paint fails. The width-reservation case asserts the hidden copy, matching the FR8 gap. | audit:ToggleButton/visual |
| FR11, FR12 | ToggleButton.test.tsx elevation and className cases |
Standalone and grouped elevation; caller className | A lost elevation, missing target, or dropped caller class fails. Evidence gap: no test reads the painted shadow or passes a caller aria-pressed or data-is-pressed. |
audit:ToggleButton/theming |
| FR8 (outer size) | Evidence gap: no test measures that pressing keeps the outer size | Labelled toggle pressed and unpressed | — | audit:ToggleButton/layout |
| FR8, FR12 (gaps) | Evidence gap: no test asserts the pressed overlay paint, the semibold pressed label, or data-is-pressed |
Pressed and unpressed | — | audit:ToggleButton/theming |
| FR14 | Evidence gap: no ToggleButton test presses or loads under prefers-reduced-motion: reduce, or loads self-colored content; the shipped scale and fade fail the reduced-motion clauses |
Mouse and touch press; pending Action with a fine pointer | A computed transform other than none or scale(1) during a press, or a Spinner opacity below 1 after it appears. |
audit:ToggleButton/behavior |
| FR10 | Evidence gap: no test of ToggleButton size precedence | — | — | audit:ToggleButton/layout |
| FR13, AR2 | ToggleButton.test.tsx children, icon-only, and width-reservation cases; ToggleButton.a11y.chromium.spec.ts state-inventory check for the rendered visible label |
Labelled; custom children; icon-only | A labelled toggle without its visible label, children that do not replace it, an icon-only toggle without aria-label, or a width copy not hidden from assistive technology fails. Evidence gap: no jsdom test asserts aria-label on a labelled toggle. |
audit:ToggleButton/accessibility |
| AR5 | ToggleButton.a11y.test.tsx and ToggleButton.a11y.chromium.spec.ts operable and focusable facts |
Standalone and grouped | A toggle that is not operable or that Tab does not reach fails. Evidence gap: no test asserts the focus indicator or the target size. | audit:ToggleButton/accessibility |
| AR4, PR1 | Evidence gap: no test asserts the absence of an automatic tooltip or the cost of the width copy | — | — | audit:ToggleButton/behavior |
Current-state impact
- Disabled focusability (FR7). A disabled ToggleButton without a tooltip
renders native
disabled, ascomponent:ButtonFR10 records, againstspec:AST-085FR1 and FR4 andfamily:buttonsFR3. The shared toggle-pattern browser states expect that nativedisabled. - Duplicated label (FR8, PR1). A labelled toggle renders a hidden semibold
copy of its label to reserve width, so
childrenmount twice, againstarchitecture:component-style-authoringINV7. - Pre-prevented click (FR3). A click already prevented before the toggle's
handler calls
onPressedChangebut notpressedChangeAction, so an Action-only toggle ignores it, againstfamily:buttonsFR5. - Reduced motion (FR14). A ToggleButton scales to 0.98 on a press, and its
Spinner fades in, when the person prefers reduced motion, against
design:reduced-motionDR1 and DR3, ascomponent:ButtonFR8 and FR15 record. - Self-colored content while pending (FR14). Content that paints its own
colors stays visible beside the Spinner, as
component:ButtonFR8 records. - Consumer docs.
ToggleButton.doc.mjssays an icon without children makes the toggle icon-only, and that icon-only adds an automatic tooltip from the label; its anatomy rows and theisIconOnlyJSDoc inToggleButton.tsxpromise the same automatic tooltip. Icon-only depends onisIconOnlyalone, and no tooltip appears withouttooltip(FR13, AR4). - Caller pressed attributes (FR12, AR1). A caller
aria-pressedordata-is-pressedreplaces ToggleButton's own, againstarchitecture:public-component-apiINV5. - Family adoption table.
family:buttonslists ToggleButton elevation as an adoption gap; the axis is shipped (FR11).
Decision log
No component-local decision. ToggleButton applies family:buttons and
component:Button.
Open questions
- OQ1 — Should ToggleButton inherit an outer size provider like Button?
(
human-api) It reads only its ownsizeand its group's (FR10); Button and IconButton also read the nearest size provider.
Content boundary
This file does not duplicate consumer prop tables/examples, current audit results, implementation steps, or family/system rules. It links to their owners.