ToggleButton
An aria-pressed two-state toggle button; the pressed state uses the primary color background. Supports size steps, icons (including icon-only form), selection color and validation status.
Basic Usage
Basic
Events
Change events
Disabled
Disabled
Size Steps (size)
size has three steps: small / medium (default) / large; control height and font size follow global tokens. When not set explicitly, the config-provider size injection is respected (global density):
Size steps
Icons (icon / icon-only)
icon takes an @oas-ui/icons registry name and renders the icon before the text (spacing via --oas-space-2). Without text it automatically becomes icon-only (square), with the icon name as the fallback accessible name — prefer providing a precise label via aria-label:
Icons and icon-only
Two-state icon (icon-toggled)
icon-toggled sets the pressed-state icon: while pressed that icon is rendered instead; on release it falls back to icon (with only icon-toggled set, nothing renders while unpressed). Orthogonal to color / variant / the icon-only form; the icon-only accessible-name fallback follows the active icon (prefer a stable aria-label):
Two-state icon (icon swaps when pressed)
Selection Color (color)
color follows the unified ui-spec protocol: any CSS color value (text color auto black/white by luminance) takes precedence; the 11 preset names (magenta / red / volcano / orange / gold / lime / green / cyan / blue / geekblue / purple) resolve to --oas-preset-* tokens (light/dark adaptive); default is the primary color. Theme-level batch customization goes through the CSS variables --oas-toggle-color / --oas-toggle-on-color:
Selection color
Validation Status (status)
status has three states: success / warning / error: borders take the semantic color and the focus ring is dyed to match; error syncs the host aria-invalid (a host-set aria-invalid="true" is equivalent to the error visuals):
Validation status
Variant
The variant dimension (aligned with the oas-button variant system, restricted to the subset meaningful for toggles): solid (default, bordered box, pressed = solid primary fill) / outlined (transparent background with border; pressed = primary border + faint tint) / filled (soft tinted background, no border; pressed = solid fill) / text (no border or background; pressed = faint tint + primary text). Invalid values silently fall back to solid; orthogonal to size / color / status (status colors win). Icon-only toolbar toggles suit text or outlined; filter panels suit filled.
Four variants (resting / pressed side by side)
Variants with real toggling (click for feedback)
API
oas-toggle-button
Attributes
| Attribute | Description | Type | Default |
|---|---|---|---|
aria-label | Accessible name (host override channel, written to the inner button) | — | — |
color | Selected color: preset name (--oas-preset-* token) or any CSS color (auto text color) | string | — |
disabled | Disabled | boolean | — |
icon | Icon (oas-icon name); icon-only renders an equal square | string | — |
icon-toggled | Pressed-state icon (oas-icon name): rendered while pressed, falls back to icon on release (with only icon-toggled set, nothing renders while unpressed); the icon-only accessible-name fallback follows the active icon | string | — |
pressed | Whether pressed (controlled) | boolean | — |
size | Size preset small / medium (default) / large | string | medium |
status | Validation status: error / warning / success; error mirrors aria-invalid | string | — |
value | Value (returned with events) | string | — |
variant | Variant (aligned with the button variant system): solid (default, bordered box, pressed = solid fill) / outlined (transparent bg + border; pressed = colored border + faint tint) / filled (soft tinted bg, no border; pressed = solid fill) / text (no border/background; pressed = faint tint + colored text); invalid values silently fall back to solid | string | — |
Property (JS property; see each row for attribute reflection)
| Property | Description | Type | Default |
|---|---|---|---|
value | Current value: the value identifier string (the pressed state is the separate pressed attribute) | string | — |
Events
| Event | Description |
|---|---|
oas-change | Toggle, detail: { value, pressed } |
Slots
| Name | Description |
|---|---|
| default | Button content (label / icon) |
CSS Variables
| CSS Variable | Default |
|---|---|
--oas-toggle-color | var(--oas-color-primary) |
--oas-toggle-on-color | var(--oas-color-text-on-primary) |
--oas-toggle-tint-text | var(--oas-color-primary-text) |