Marble UI
← Components

Toggle Button Group

Preview: Single

Group of ToggleButtons with single or multiple selection and arrow-key navigation.

Import

import { ToggleButtonGroup } from '@marbleui/ui'

Props

<ToggleButtonGroup>

PropTypeDefaultDescription
variant'attached' | 'spaced''attached'

Also accepts React Aria props (86).

Accessibility

Keyboard interaction, focus management and ARIA semantics come from the underlying primitive: React Aria ToggleButtonGroup. Follow the primitive's docs for the full keyboard map.

Usage notes

Groups ToggleButtons that share a selection, either one at a time or several. For a mutually exclusive view switcher with a sliding indicator use SegmentedControl; for non-selecting buttons use ButtonGroup.

<ToggleButtonGroup aria-label="Alignment" selectionMode="single" disallowEmptySelection defaultSelectedKeys={['left']}>
  <ToggleButton id="left" aria-label="Align left"><AlignLeftIcon /></ToggleButton>
  <ToggleButton id="center" aria-label="Align center"><AlignCenterIcon /></ToggleButton>
</ToggleButtonGroup>
  • Each ToggleButton needs an id; selection is a set of those ids. Uncontrolled: defaultSelectedKeys. Controlled: selectedKeys + onSelectionChange.
  • selectionMode is single or multiple. Add disallowEmptySelection to force one choice.
  • variant: attached (default) or spaced. Arrow keys move between buttons.
  • Pass aria-label; icon-only buttons need their own.
Example source · show
import { ToggleButton } from '../toggle-button'
import { ToggleButtonGroup } from './toggle-button-group'

const I = ({ d }: { d: string }) => (
  <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" strokeWidth="2" strokeLinecap="round" aria-hidden>
    <path d={d} />
  </svg>
)

export const styles = {
  Single: () => (
    <ToggleButtonGroup aria-label="Alignment" selectionMode="single" disallowEmptySelection defaultSelectedKeys={['left']}>
      <ToggleButton id="left" aria-label="Align left"><I d="M21 6H3M15 12H3M17 18H3" /></ToggleButton>
      <ToggleButton id="center" aria-label="Align center"><I d="M21 6H3M17 12H7M19 18H5" /></ToggleButton>
      <ToggleButton id="right" aria-label="Align right"><I d="M21 6H3M21 12H9M21 18H7" /></ToggleButton>
    </ToggleButtonGroup>
  ),
  Multiple: () => (
    <ToggleButtonGroup aria-label="Text style" selectionMode="multiple" variant="spaced" defaultSelectedKeys={['bold']}>
      <ToggleButton id="bold" variant="soft">Bold</ToggleButton>
      <ToggleButton id="italic" variant="soft">Italic</ToggleButton>
      <ToggleButton id="strike" variant="soft">Strike</ToggleButton>
    </ToggleButtonGroup>
  ),
}

Source: packages/ui/src/toggle-button-group/toggle-button-group.tsx

Catalog

Category
inputs
Priority
Core
Primitive
react-aria
React Aria
ToggleButtonGroup
Base UI
Toggle Group