Components Actions
ToggleButton
StableA button that stays pressed, alone or in a group with single or multiple selection.
Use ToggleButton for a setting that switches on and off in place, like bold text or showing gridlines. ToggleButtonGroup arranges several toggles with one tab stop and arrow-key navigation: type="single" works like a segmented control (alignment, view mode) and type="multiple" allows any combination (text formatting). For settings that take effect as preferences, prefer Switch.
Overview
import { Icon, ToggleButton, ToggleButtonGroup } from '@bindshq/stance-react';
export function Single() {
return (
<ToggleButtonGroup label="Template view" defaultValue="grid" required>
<ToggleButton value="grid" icon={<Icon name="layout-grid" />}>
Grid
</ToggleButton>
<ToggleButton value="list" icon={<Icon name="list" />}>
List
</ToggleButton>
</ToggleButtonGroup>
);
}Light, dark and high contrast
Every Stance component is designed and tested in all three appearance modes.
Import
import { ToggleButton, ToggleButtonGroup } from '@bindshq/stance-react';Platforms
ToggleButton has native counterparts. They share Stance tokens and intent, and use each platform’s own controls and conventions. The live previews on this page are the web implementation.
import { ToggleButton, ToggleButtonGroup } from '@bindshq/stance-react';Examples
import { Icon, ToggleButton } from '@bindshq/stance-react';
export function Standalone() {
return (
<ToggleButton defaultPressed icon={<Icon name="eye" />}>
Show placeholders
</ToggleButton>
);
}import { ToggleButton, ToggleButtonGroup } from '@bindshq/stance-react';
export function Multiple() {
return (
<ToggleButtonGroup
type="multiple"
label="Show in signature"
defaultValue={['phone', 'logo']}
attached={false}
>
<ToggleButton value="phone">Phone</ToggleButton>
<ToggleButton value="address">Address</ToggleButton>
<ToggleButton value="logo">Logo</ToggleButton>
<ToggleButton value="social">Social links</ToggleButton>
</ToggleButtonGroup>
);
}Previewing on: desktop
import * as React from 'react';
import { Icon, ToggleButton, ToggleButtonGroup } from '@bindshq/stance-react';
export function Controlled() {
const [value, setValue] = React.useState<string | null>('desktop');
return (
<div style={{ display: 'grid', gap: 12, justifyItems: 'start' }}>
<ToggleButtonGroup
label="Preview device"
value={value}
onValueChange={setValue}
required
size="sm"
>
<ToggleButton value="desktop" icon={<Icon name="monitor" />}>
Desktop
</ToggleButton>
<ToggleButton value="mobile">Mobile</ToggleButton>
</ToggleButtonGroup>
<span style={{ fontSize: 14 }}>Previewing on: {value}</span>
</div>
);
}API reference
ToggleButton
| Prop | Type | Default | Description |
|---|---|---|---|
pressed | boolean | None | Controlled pressed state (standalone). |
defaultPressed | boolean | false | Initial pressed state (standalone). |
onPressedChange | (pressed: boolean) => void | None | Called when toggled. |
value | string | None | Identifies the button inside a group. |
icon | ReactNode | None | Icon before the label. |
size | 'sm' | 'md' | 'lg' | 'md' | Inherited from the group. |
ToggleButtonGroup
| Prop | Type | Default | Description |
|---|---|---|---|
type | 'single' | 'multiple' | 'single' | Selection mode. |
value | string | null | string[] | None | Controlled value: a string (single) or array (multiple). |
defaultValue | string | null | string[] | None | Initial value. |
onValueChange | (value) => void | None | Called with the new value. |
required | boolean | false | Single mode: prevent clearing the selection. |
label | string | None | Accessible name for the group. |
attached | boolean | true | Join buttons into a segmented bar. |
orientation | 'horizontal' | 'vertical' | 'horizontal' | Layout and arrow-key axis. |
Accessibility
- Each toggle exposes aria-pressed, so assistive technology announces "pressed" or "not pressed".
- The group has one tab stop: Tab enters on the selected item and arrow keys move between items (roving tabindex).
- Keep the label constant while toggling; the pressed state communicates the change, not a new label.
Keyboard
| Keys | Action |
|---|---|
| Space Enter | Toggles the focused button. |
| ArrowRight ArrowLeft | Moves focus within a horizontal group. |
| ArrowDown ArrowUp | Moves focus within a vertical group. |
| Home End | Moves to the first or last button. |
Usage guidelines
Do
- Use icons with text, or provide aria-label on icon-only toggles.
Don’t
- Change the button label when its state changes.