All components
Actions

ButtonGroup

stable
Since 1.1
Joined group of adjacent segments: an action group, or a single- or multiple-selection control with group and per-item disabled states.
Actions
primitive
Display
Documented
import { ButtonGroup } from '@ivim/native/components';

When to use

Use when
A small set of mutually exclusive views or filters should all be visible at once.
Several related actions belong together visually as one control.
Don't use when
You just need a row of separate buttons with spacing — use Inline or Cluster; this component draws a joined control.
There are more than about five options, or the labels are long — use Select so the list can scroll.
The choice is binary and reads as on/off — use Toggle.

Playground

Adjust the controls to preview live prop combinations. The code snippet updates to match the current selection.
Selection mode
selectionMode
size
size
orientation
orientation
Disabled
isDisabled
Full width
fullWidth
<ButtonGroup selectionMode="single" />

Example

Selection modes
Single selection (radiogroup)
Multiple selection
Action group (holds no state)
Content and layout
With status dots
With icons (leading and trailing)
Sizes (sm, md, lg)
Vertical, full width
Disabled states
One disabled item
Whole group disabled

Anatomy

The parts that compose this component.
1
Group container
Carries the shared outer border and radius, and clips segment corners. Announces as radiogroup or toolbar.
2
Segment
One pressable per item, announcing as radio, checkbox, or button depending on selection mode.
3
Divider
A single border on each segment’s leading edge, so adjacent segments never render a doubled line.
4
Dot
Optional status indicator before the label.

Guidelines

Do
Keep labels short and parallel in form, so the segments read as one set.
Do
Use selectionMode="single" for mutually exclusive views and "multiple" for independent filters.
Don't
Use this as a layout wrapper for unrelated buttons — it announces as a radiogroup or toolbar and implies the items are one set.
Don't
Disable the whole group to communicate loading; disable the surrounding action instead so the current value stays readable.

Props

Public props for this component. Required props are marked; defaults reflect the component implementation.
items
required
ButtonGroupItem[]
Segments: { key, label, iconLeading?, iconTrailing?, dot?, dotColor?, isDisabled? }.
selectionMode
'none' | 'single' | 'multiple'
default: 'none'
none is an action group holding no state; single and multiple make it a selection control.
selectedKey / defaultSelectedKey
string | null
Controlled and uncontrolled selection for single mode.
selectedKeys / defaultSelectedKeys
string[]
Controlled and uncontrolled selection for multiple mode.
onSelectionChange
(keys: string[]) => void
Always an array, including in single mode.
onAction
(key: string) => void
Fires for every activation, including in action mode.
isDisabled
boolean
default: false
Disables the whole group, overriding per-item state.
orientation
'horizontal' | 'vertical'
default: 'horizontal'
Segment stacking direction.
size
'sm' | 'md' | 'lg'
default: 'md'
Segment height, padding, and label scale.
fullWidth
boolean
default: false
Stretches the group and distributes segments evenly.
aria-label
string
Accessible name when there is no visible label, or when the label is not plain text.

Accessibility

Roles and screen-reader behavior this component provides, plus keyboard interactions.
•
The group announces as radiogroup in single mode and toolbar otherwise; it is intentionally not an accessibility element itself, so each segment stays individually reachable.
•
Segments announce as radio, checkbox, or button to match the selection mode, and carry checked and disabled state.
•
Arrow keys move the selection in single mode, following the WAI-ARIA radiogroup pattern, and move focus in the other modes.
•
Roving tabindex gives the group one tab stop rather than one per segment.
•
A group-level isDisabled overrides every item, so a disabled group can never be partially operable.
Tab
Moves focus into the group (one stop).
Arrow Right / Down
Next segment; selects it in single mode.
Arrow Left / Up
Previous segment; selects it in single mode.
Home / End
First or last enabled segment.
Space / Enter
Activates the focused segment.

Platform & RTL

Behavior that differs across the platforms this component runs on.
Web
Full arrow-key traversal with a roving tabindex; focus follows the selection.
iOS
Touch only — arrow-key traversal has no native equivalent, and each segment is reachable directly by VoiceOver.
Android
Touch only, matching iOS; TalkBack reaches each segment directly.
RTL
Segment order and the leading divider mirror with the writing direction.

State coverage

Interaction and visual states this component supports.
base
semantic color
density

Token references

Semantic design tokens this component page exercises. Tap one to edit it live.

Related components

Components that solve adjacent problems or compose with this one.
Button
Action control with four emphasis variants, three semantic tones, five sizes, icon slots, loading, and navigational semantics.
SegmentedControl
Controlled segmented selection primitive for compact view switching.
TagGroup
A row of tags: static labels, or single/multiple selection, with per-tag and group removal, dots, counts, and avatar slots.
RadioGroup
One-of-many choice as a list or as selectable cards, with icon, avatar, price, badge, and secondary-action slots.
Previous: Button
Next: Utility buttons