XDS — Design System

XDSToggleButtonGroup@xds/core · ToggleButton

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.

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.

Anatomy

Element		Description
Icon		A leading icon that represents the toggle action, like a star for favorite or bold "B" for formatting.
Pressed icon		An alternate icon shown when pressed — typically a filled version of the default icon to reinforce the active state.
Label	required	The visible text or accessible name. For icon-only toggles, used as the aria-label and auto-tooltip.
Spinner		Replaces the icon during async operations triggered by pressedChangeAction.

Import

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

Props

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.

Showcase source

tsx
'use client';
import {useState} from 'react';
import {
  XDSToggleButton,
  XDSToggleButtonGroup,
} from '@xds/core/ToggleButton';
import {XDSVStack} from '@xds/core/Layout';
import {XDSText} from '@xds/core/Text';
export default function ToggleButtonGroupShowcase() {
  const [view, setView] = useState<string | null>('grid');
  const [filters, setFilters] = useState<string[]>(['active']);
  return (
    <XDSVStack gap={4}>
      <XDSVStack gap={1}>
        <XDSText type="label" color="secondary">
          Single select
        </XDSText>
        <XDSToggleButtonGroup value={view} onChange={setView} label="View mode">
          <XDSToggleButton value="list" label="List" />
          <XDSToggleButton value="grid" label="Grid" />
          <XDSToggleButton value="board" label="Board" />
        </XDSToggleButtonGroup>
      </XDSVStack>
      <XDSVStack gap={1}>
        <XDSText type="label" color="secondary">
          Multi select
        </XDSText>
        <XDSToggleButtonGroup
          type="multiple"
          value={filters}
          onChange={setFilters}
          label="Status filters">
          <XDSToggleButton value="active" label="Active" />
          <XDSToggleButton value="pending" label="Pending" />
          <XDSToggleButton value="closed" label="Closed" />
        </XDSToggleButtonGroup>
      </XDSVStack>
    </XDSVStack>
  );
}