ToggleButtonGroup

A container for toggle buttons with single or multiple selection.

Usage#

import { ToggleButtonGroup, ToggleButton } from '@backstage/ui';

<ToggleButtonGroup selectionMode="single">
  <ToggleButton id="dogs">Dogs</ToggleButton>
  <ToggleButton id="cats">Cats</ToggleButton>
  <ToggleButton id="birds">Birds</ToggleButton>
</ToggleButtonGroup>

API reference#

Prop	Type	Default	Description
selectionMode	singlemultiple	-	Whether to allow single or multiple selection.
selectedKeys	Iterable<Key>	-	The currently selected keys (controlled).
defaultSelectedKeys	Iterable<Key>	-	The initial selected keys (uncontrolled).
onSelectionChange	(keys: Selection) => void	-	Handler called when the selection changes.
orientation	horizontalvertical	horizontal	The layout orientation of the button group.
disallowEmptySelection	boolean	-	Whether to prevent deselecting when at least one button is selected.
isDisabled	boolean	false	Disables all buttons in the group.
disabledKeys	Iterable<Key>	-	Keys of buttons that should be disabled.
children	ReactNode	-
className	string	-	Additional CSS class name for custom styling.

Inherits all React Aria ToggleButtonGroup props.

Examples#

Surfaces#

Default

On Surface 0

On Surface 1

On Surface 2

On Surface 3

Single selection#

<ToggleButtonGroup selectionMode="single" defaultSelectedKeys={['dogs']}>
  <ToggleButton id="dogs">Dogs</ToggleButton>
  <ToggleButton id="cat">Cats</ToggleButton>
  <ToggleButton id="bird">Birds</ToggleButton>
</ToggleButtonGroup>

Multiple selection#

<ToggleButtonGroup selectionMode="multiple" defaultSelectedKeys={['frontend']}>
  <ToggleButton id="frontend">Frontend</ToggleButton>
  <ToggleButton id="backend">Backend</ToggleButton>
  <ToggleButton id="platform">Platform</ToggleButton>
</ToggleButtonGroup>

Icons and text#

import { RiCloudLine, RiStarFill, RiStarLine, RiArrowRightSLine } from '@remixicon/react';

<ToggleButtonGroup selectionMode="multiple" defaultSelectedKeys={['cloud']}>
  <ToggleButton id="cloud" aria-label="Cloud" iconStart={<RiCloudLine />} />
  <ToggleButton
    id="starred"
    aria-label="Starred"
    iconStart={<RiStarFill />}
  />
  <ToggleButton id="star" iconStart={<RiStarLine />}>
    Star
  </ToggleButton>
  <ToggleButton id="next" iconEnd={<RiArrowRightSLine />}>
    Next
  </ToggleButton>
</ToggleButtonGroup>

Icons only#

import { RiCloudLine, RiStarLine, RiArrowRightSLine } from '@remixicon/react';

<ToggleButtonGroup selectionMode="multiple" defaultSelectedKeys={['cloud']}>
  <ToggleButton id="cloud" aria-label="Cloud" iconStart={<RiCloudLine />} />
  <ToggleButton id="star" aria-label="Star" iconStart={<RiStarLine />} />
  <ToggleButton id="next" aria-label="Next" iconEnd={<RiArrowRightSLine />} />
</ToggleButtonGroup>

Disallow empty selection#

<ToggleButtonGroup selectionMode="single" disallowEmptySelection defaultSelectedKeys={['one']}>
  <ToggleButton id="one">One</ToggleButton>
  <ToggleButton id="two">Two</ToggleButton>
  <ToggleButton id="three">Three</ToggleButton>
</ToggleButtonGroup>

Vertical orientation#

<ToggleButtonGroup selectionMode="single" orientation="vertical">
  <ToggleButton id="morning">Morning</ToggleButton>
  <ToggleButton id="afternoon">Afternoon</ToggleButton>
  <ToggleButton id="evening">Evening</ToggleButton>
</ToggleButtonGroup>

Disabled#

<ToggleButtonGroup selectionMode="single" isDisabled>
  <ToggleButton id="cat">Cat</ToggleButton>
  <ToggleButton id="dog">Dog</ToggleButton>
  <ToggleButton id="bird">Bird</ToggleButton>
</ToggleButtonGroup>

Theming#

Our theming system is based on a mix between CSS classes, CSS variables and data attributes. If you want to customise this component, you can use one of these class names below.

bui-ToggleButtonGroup