ToggleButtonGroup

A control for picking one or several options from a linear set of closely related options; useful for filtering or sorting.

Installation

npm install @xsolla/xui-toggle-button-group

Imports

import { ToggleButtonGroup } from '@xsolla/xui-toggle-button-group';
import type {
  ToggleButtonGroupProps,
  ToggleButtonGroupItem,
  ToggleButtonGroupSize,
  ToggleButtonGroupAppearance,
} from '@xsolla/xui-toggle-button-group';

Quick start

onChange is typed (value: string | string[]) => void regardless of multiple, so single-select callers cast the value to string.

const [value, setValue] = useState('item1');

<ToggleButtonGroup
  items={[
    { id: 'item1', label: 'Option 1' },
    { id: 'item2', label: 'Option 2' },
    { id: 'item3', label: 'Option 3' },
  ]}
  value={value}
  onChange={(v) => setValue(v as string)}
/>;

API Reference

<ToggleButtonGroup>

| Prop | Type | Default | Description | | --- | --- | --- | --- | | items | ToggleButtonGroupItem[] | — | Items to display. | | value | string \| string[] | — | Controlled value; string for single, array for multiple. | | defaultValue | string \| string[] | — | Initial value for uncontrolled mode. | | onChange | (value: string \| string[]) => void | — | Fired when the selection changes. | | size | 'xs' \| 'sm' \| 'md' \| 'lg' \| 'xl' | 'md' | Size variant. | | appearance | 'separated' \| 'united' | 'separated' | separated adds gaps; united connects items. | | view | 'horizontal' \| 'vertical' | 'horizontal' | Stack items in a row or column. | | multiple | boolean | false | Allow multiple selections. | | fullWidth | boolean | false | Stretch to fill the container. | | id | string | — | HTML id. | | testID | string | — | Test identifier. | | aria-label | string | — | Accessible label for the group. | | aria-labelledby | string | — | ID of an element that labels the group. |

Inherits ThemeOverrideProps (themeMode, themeProductContext).

ToggleButtonGroupItem

| Field | Type | Description | | --- | --- | --- | | id | string | Unique identifier. | | label | string | Display text. | | iconLeft | ReactNode | Icon shown before the label. | | iconRight | ReactNode | Icon shown after the label. | | disabled | boolean | Disable the individual item. | | aria-label | string | Accessible label for the item. |

Types

type ToggleButtonGroupSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
type ToggleButtonGroupAppearance = 'separated' | 'united';
type ToggleButtonGroupView = 'horizontal' | 'vertical';

Examples

Multiple selection

onChange is still typed (value: string | string[]) => void, so multi-select callers cast the value to string[].

const [values, setValues] = useState(['item1', 'item3']);

<ToggleButtonGroup
  multiple
  items={[
    { id: 'item1', label: 'Option 1' },
    { id: 'item2', label: 'Option 2' },
    { id: 'item3', label: 'Option 3' },
  ]}
  value={values}
  onChange={(v) => setValues(v as string[])}
/>

United appearance, full width

<ToggleButtonGroup
  appearance="united"
  fullWidth
  items={[
    { id: 'day', label: 'Day' },
    { id: 'week', label: 'Week' },
    { id: 'month', label: 'Month' },
  ]}
  defaultValue="week"
/>

Accessibility

• role="radiogroup" for single selection, role="group" for multiple selection.
• Arrow keys move between items; Enter/Space toggles selection.
• aria-checked and aria-disabled reflect item state.