SegmentedButton

MD3 segmented buttons: a row of equal-width outlined segments for choosing one option or several. Selected segments fill with the secondary container and show a check in an always-reserved icon slot, so the row never jumps.

Expressive alternative

In Material 3 Expressive, connected button groups replace segmented buttons. For new designs prefer <ButtonGroup variant="connected" selectionMode="single">. SegmentedButton stays available and is not deprecated.

Single select

Pass the segments as options; control the selection with value / onChange(event, value) or leave it uncontrolled with defaultValue.

const [value, setValue] = useState('week')

<SegmentedButton
  aria-label="Calendar view"
  value={value}
  onChange={(event, next) => setValue(next as string)}
  options={[
    { value: 'day', label: 'Day' },
    { value: 'week', label: 'Week' },
    { value: 'month', label: 'Month' },
  ]}
/>

Multi select

With multiSelect the value is a string[].

<SegmentedButton
  multiSelect
  defaultValue={['s', 'm']}
  onChange={(event, values) => setSizes(values as string[])}
  options={sizes}
  aria-label="Sizes"
/>

Icons

A segment with both icon and label shows the icon, which crossfades to the check while selected. Without a label the segment is icon-only: the icon stays and the check appears beside it — give each such segment an ariaLabel.

<SegmentedButton
  aria-label="Text alignment"
  defaultValue="left"
  options={[
    { value: 'left', icon: <AlignLeftIcon />, ariaLabel: 'Align left' },
    { value: 'center', icon: <AlignCenterIcon />, ariaLabel: 'Align center' },
    { value: 'right', icon: <AlignRightIcon />, ariaLabel: 'Align right' },
  ]}
/>

showSelectedCheck={false} hides the check on selected segments.

Disabled

Disable the whole group with disabled, or a single segment with the option's disabled.

Accessibility

• Single select renders a radiogroup of radios (aria-checked) with one Tab stop: arrow keys move focus, Space / Enter select.
• Multi select renders a group of toggle buttons (aria-pressed); each segment is a Tab stop, and arrow keys also move focus.
• Name the group with aria-label / aria-labelledby, and give icon-only segments an ariaLabel describing the option.

Props

Prop	Type	Default	Description
defaultValue	string | string[]	—	Uncontrolled initial selection. Defaults to none (`''`, or `[]` when `multiSelect`).
disabled	boolean	false	Disable the whole group.
multiSelect	boolean	false	Allow selecting multiple segments. Single-select renders a `radiogroup` of radios; multi-select renders a `group` of toggle buttons (`aria-pressed`).
onChange	((event: MouseEvent<HTMLButtonElement, MouseEvent>, value: string | string[]) => void)	—	Fires with the triggering event and the next selection (string, or string[] when `multiSelect`). Keyboard activation (Space / Enter) arrives as the native button `click`.
options *	SegmentedButtonOption[]	—	The segments.
showSelectedCheck	boolean	true	Show a check icon on selected segments.
value	string | string[]	—	Controlled selected value (string) — or an array of values when `multiSelect`.