XDS — Design System

ToggleButton@xds/core v0.0.13 · XDSToggleButton

Usage

ToggleButton switches between selected and unselected states to represent a persistent on/off choice. Use it standalone for binary actions like bold, mute, or favorite, or inside a ToggleButtonGroup for single-select or multi-select toolbar controls.

ts
import {XDSToggleButton} from '@xds/core/ToggleButton'

Best practices

Guidance	Practices
Do	Use a filled or colored icon for the pressed state so users can see the current state at a glance — an outline star vs a solid star, for example.
Do	Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.
Do	Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set.
Don't	Don't use a ToggleButton for one-time actions like "Submit" or "Delete" — those are regular Buttons, not toggles.
Don't	Don't mix ToggleButtons with regular Buttons inside the same group — use only ToggleButtons in a ToggleButtonGroup.
Don't	Don't use a ToggleButton for on/off settings that persist across sessions — use a Switch instead, which better communicates "setting" semantics.

Sub-components

ToggleButton is a compound component with 2 sub-components.

XDSToggleButton

A button that toggles between pressed and unpressed states. Thin wrapper over XDSButton with controlled toggle pattern, icon swap, and font weight emphasis.

Prop	Type	Description
labelrequired	string	Accessible label for the button. Used as visible text, or as aria-label for icon-only buttons.
isPressed	boolean	Whether the button is currently pressed. Ignored when inside a group.
onPressedChange	(isPressed: boolean) => void	Called when pressed state should change. Ignored when inside a group.
pressedChangeAction	(isPressed: boolean) => Promise<void>	Async action handler for API-backed toggles. Shows loading spinner while pending.
size	'sm' \| 'md' \| 'lg' (default: 'md')	Button size. Defaults to group size when inside a group.
isDisabled	boolean (default: false)	Whether the button is disabled.
isLoading	boolean (default: false)	Whether the button shows a loading spinner.
icon	ReactNode	Icon element. When provided without children, button becomes icon-only with tooltip from label.
pressedIcon	ReactNode	Icon shown when pressed. Falls back to icon if not provided.
children	ReactNode	Visible content. If omitted with icon, button becomes icon-only.
tooltip	string	Tooltip text shown on hover.
value	string	Value identifier when used inside XDSToggleButtonGroup. Required in groups.
data-testid	string	Test selector for automated testing frameworks.

XDSToggleButtonGroup

Groups toggle buttons for exclusive (single) or multi-select behavior. Uses discriminated union on type for type-safe value/onChange.

Prop	Type	Description
childrenrequired	ReactNode	XDSToggleButton children.
labelrequired	string	Accessible label for the group (aria-label).
valuerequired	string \| null \| string[]	Currently selected value(s). Type depends on selection mode.
onChangerequired	(value: string \| null \| string[]) => void	Called when selection changes.
type	'single' \| 'multiple' (default: 'single')	Selection mode. Single allows one active button, multiple allows many.
orientation	'horizontal' \| 'vertical' (default: 'horizontal')	Layout direction of the button group.
size	'sm' \| 'md' \| 'lg' (default: 'md')	Default size for buttons in the group. Individual buttons can override.
isDisabled	boolean (default: false)	Whether all buttons in the group are disabled.
xstyle	StyleXStyles	StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.
data-testid	string	Test selector for automated testing frameworks.

Examples

Common configurations, variations, and states.

ToggleButton — Color

Toggle buttons with colored icons in the pressed state. Shows accent-colored toolbar formatting and semantic reaction colors (yellow star, red heart, blue bookmark).

ToggleButton — Group

Toggle button groups in single-select and multi-select modes. Single selection acts as a view mode switcher; multiple selection forms a formatting toolbar.

ToggleButton — Icon Swap

Icon-only toggle buttons that swap between outline and solid icons when pressed. Use for actions like favorite, bookmark, or mute where the icon itself communicates the state.

ToggleButton — Label

Toggle buttons with visible text labels that show a font weight shift on press. Use when the icon alone is not enough to communicate the action.

ToggleButton — States

Default, pressed, disabled, and loading states of a standalone toggle button. Shows how visual treatment changes across states.

Usage

import {XDSToggleButton} from '@xds/core/ToggleButton'

Best practices

Guidance	Practices
Do	Use a filled or colored icon for the pressed state so users can see the current state at a glance — an outline star vs a solid star, for example.
Do	Keep the label identical between pressed and unpressed states. Let the visual treatment (icon, weight, background) communicate the change.
Do	Wrap related toggles in a ToggleButtonGroup with an accessible label so screen readers announce them as a connected set.
Don't	Don't use a ToggleButton for one-time actions like "Submit" or "Delete" — those are regular Buttons, not toggles.
Don't	Don't mix ToggleButtons with regular Buttons inside the same group — use only ToggleButtons in a ToggleButtonGroup.
Don't	Don't use a ToggleButton for on/off settings that persist across sessions — use a Switch instead, which better communicates "setting" semantics.

Prop

Type

Description

labelrequired

string

Accessible label for the button. Used as visible text, or as aria-label for icon-only buttons.

isPressed

boolean

Whether the button is currently pressed. Ignored when inside a group.

onPressedChange

(isPressed: boolean) => void

Called when pressed state should change. Ignored when inside a group.

pressedChangeAction

(isPressed: boolean) => Promise<void>

Async action handler for API-backed toggles. Shows loading spinner while pending.

size

'sm' | 'md' | 'lg' (default: 'md')

Button size. Defaults to group size when inside a group.

isDisabled

boolean (default: false)

Whether the button is disabled.

isLoading

boolean (default: false)

Whether the button shows a loading spinner.

icon

ReactNode

Icon element. When provided without children, button becomes icon-only with tooltip from label.

pressedIcon

ReactNode

Icon shown when pressed. Falls back to icon if not provided.

children

ReactNode

Visible content. If omitted with icon, button becomes icon-only.

tooltip

string

Tooltip text shown on hover.

value

string

Value identifier when used inside XDSToggleButtonGroup. Required in groups.

data-testid

string

Test selector for automated testing frameworks.

Prop

Type

Description

childrenrequired

ReactNode

XDSToggleButton children.

labelrequired

string

Accessible label for the group (aria-label).

valuerequired

string | null | string[]

Currently selected value(s). Type depends on selection mode.

onChangerequired

(value: string | null | string[]) => void

Called when selection changes.

type

'single' | 'multiple' (default: 'single')

Selection mode. Single allows one active button, multiple allows many.

orientation

'horizontal' | 'vertical' (default: 'horizontal')

Layout direction of the button group.

size

'sm' | 'md' | 'lg' (default: 'md')

Default size for buttons in the group. Individual buttons can override.

isDisabled

boolean (default: false)

Whether all buttons in the group are disabled.

xstyle

StyleXStyles

StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value.

data-testid

string

Test selector for automated testing frameworks.