Segmented buttons
Material segmented controls with single-choice radio semantics and multi-choice checkbox semantics kept distinct.
Segmented buttons group a small set of related choices in one connected Material surface. m3-ui exposes separate single-choice and multi-choice primitives so the visual family does not blur two different selection models.
import {
SingleChoiceSegmentedButton,
SingleChoiceSegmentedButtonRow,
} from '@m3-ui/ui';
<SingleChoiceSegmentedButtonRow aria-label="Density" defaultValue="standard">
<SingleChoiceSegmentedButton value="compact">Compact</SingleChoiceSegmentedButton>
<SingleChoiceSegmentedButton value="standard">Standard</SingleChoiceSegmentedButton>
</SingleChoiceSegmentedButtonRow>When to use
Use segmented buttons for a small set of closely related choices that benefit from visible connected alternatives. Prefer radio buttons when the option set is larger or clearer as a conventional form group, and prefer checkboxes when independent choices do not need a connected segmented presentation.
Single choice
SingleChoiceSegmentedButtonRow with SingleChoiceSegmentedButton uses one-of-many radio-group/radio semantics. Every segment has a value, and the group owns exactly one current selection.
<SingleChoiceSegmentedButtonRow aria-label="View" defaultValue="list">
<SingleChoiceSegmentedButton value="list">List</SingleChoiceSegmentedButton>
<SingleChoiceSegmentedButton value="grid">Grid</SingleChoiceSegmentedButton>
</SingleChoiceSegmentedButtonRow>Multiple choice
MultiChoiceSegmentedButtonRow groups independent selectable segments. Each MultiChoiceSegmentedButton uses checkbox/toggle selection semantics so multiple segments can be active simultaneously.
<MultiChoiceSegmentedButtonRow aria-label="Text formatting">
<MultiChoiceSegmentedButton defaultSelected>Bold</MultiChoiceSegmentedButton>
<MultiChoiceSegmentedButton>Italic</MultiChoiceSegmentedButton>
</MultiChoiceSegmentedButtonRow>Do not describe multi-choice rows as a radio group or single-choice rows as independent toggles. Their browser semantics intentionally differ.
Icons and selected state
Segments may provide an inactive icon and a selectedIcon. If no selected icon is supplied, the component can render the Material selected mark. Icons are presentation; the segment label and control semantics remain the accessible source of meaning.
Canonical outline, connected shape, spacing, state layers, typography, and selected/unselected colors come from component tokens rather than docs-owned CSS values.
Accessibility
React Aria provides the appropriate radio or checkbox/toggle keyboard and selection behavior. Keep the row's accessible label meaningful and let the selected state communicate through the correct semantic model rather than adding custom key handlers.
Each segment should have a clear visible or accessible label. Do not rely on selected color or icon alone to convey the active choice.
API reference
SingleChoiceSegmentedButtonRow
SingleChoiceSegmentedButtonRow({ children, className, style, ...props }: SingleChoiceSegmentedButtonRowProps): JSX.ElementProps
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
children* | ReactNode | — | — | @m3-ui/ui |
Inherited React / web props (93)
| Name | Type | Default | Description | Origin |
|---|---|---|---|---|
aria-describedby | string | undefined | — | Identifies the element (or elements) that describes the object. | @react-types/shared |
aria-details | string | undefined | — | Identifies the element (or elements) that provide a detailed, extended description for the object. | @react-types/shared |
aria-errormessage | string | undefined | — | Identifies the element that provides an error message for the object. | @react-types/shared |
aria-label | string | undefined | — | Defines a string value that labels the current element. | @react-types/shared |
aria-labelledby | string | undefined | — | Identifies the element (or elements) that labels the current element. | @react-types/shared |
className | ClassNameOrFunction<RadioGroupRenderProps> | undefined | 'react-aria-RadioGroup' | The CSS [className](https://developer.mozilla.org/en-US/docs/Web/API/Element/className) for the element. A function may be provided to compute the class based on component state. | react-aria-components |
defaultValue | string | null | undefined | — | The default value (uncontrolled). | @react-types/shared |
dir | string | undefined | — | — | @react-types/shared |
form | string | undefined | — | The `<form>` element to associate the input with. The value of this attribute must be the id of a `<form>` in the same document. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Reference/Elements/input#form). | @react-types/shared |
hidden | boolean | undefined | — | — | @react-types/shared |
id | string | undefined | — | The element's unique identifier. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/id). | @react-types/shared |
inert | boolean | undefined | — | — | @react-types/shared |
isDisabled | boolean | undefined | — | Whether the input is disabled. | @react-types/shared |
isInvalid | boolean | undefined | — | Whether the input value is invalid. | @react-types/shared |
isReadOnly | boolean | undefined | — | Whether the input can be selected but not changed by the user. | @react-types/shared |
isRequired | boolean | undefined | — | Whether user input is required on the input before form submission. | @react-types/shared |
lang | string | undefined | — | — | @react-types/shared |
name | string | undefined | — | The name of the input element, used when submitting an HTML form. See [MDN](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefname). | @react-types/shared |
onAnimationEnd | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationEndCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIteration | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationIterationCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStart | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAnimationStartCapture | AnimationEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onAuxClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onBlur | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element loses focus. | @react-types/shared |
onChange | ((value: string) => void) | undefined | — | Handler that is called when the value changes. | @react-types/shared |
onClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenu | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onContextMenuCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClick | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onDoubleClickCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onFocus | ((e: FocusEvent<Element, Element>) => void) | undefined | — | Handler that is called when the element receives focus. | @react-types/shared |
onFocusChange | ((isFocused: boolean) => void) | undefined | — | Handler that is called when the element's focus status changes. | @react-types/shared |
onGotPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onGotPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onLostPointerCaptureCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDown | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseDownCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseEnter | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseLeave | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMove | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseMoveCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOut | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOutCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOver | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseOverCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUp | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onMouseUpCapture | MouseEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancel | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerCancelCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDown | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerDownCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerEnter | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerLeave | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMove | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerMoveCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOut | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOutCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOver | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerOverCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUp | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onPointerUpCapture | PointerEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScroll | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onScrollCapture | UIEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancel | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchCancelCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEnd | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchEndCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMove | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchMoveCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStart | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTouchStartCapture | TouchEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancel | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionCancelCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEnd | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionEndCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRun | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionRunCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStart | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onTransitionStartCapture | TransitionEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheel | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
onWheelCapture | WheelEventHandler<HTMLDivElement> | undefined | — | — | @react-types/shared |
render | DOMRenderFunction<"div", RadioGroupRenderProps> | undefined | — | Overrides the default DOM element with a custom render function. This allows rendering existing components with built-in styles and behaviors such as router links, animation libraries, and pre-styled components. Requirements: - You must render the expected element type (e.g. if `<button>` is expected, you cannot render an `<a>`). - Only a single root DOM element can be rendered (no fragments). - You must pass through props and ref to the underlying DOM element, merging with your own prop as appropriate. | react-aria-components |
slot | string | null | undefined | — | A slot name for the component. Slots allow the component to receive props from a parent component. An explicit `null` value indicates that the local props completely override all props received from a parent. | react-aria-components |
style | StyleOrFunction<RadioGroupRenderProps> | undefined | — | The inline [style](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement/style) for the element. A function may be provided to compute the style based on component state. | react-aria-components |
translate | "yes" | "no" | undefined | — | — | @react-types/shared |
validate | ((value: string) => ValidationError | true | null | undefined) | undefined | — | A function that returns an error message if a given value is invalid. Validation errors are displayed to the user when the form is submitted if `validationBehavior="native"`. For realtime validation, use the `isInvalid` prop instead. | @react-types/shared |
validationBehavior | "native" | "aria" | undefined | 'native' | Whether to use native HTML form validation to prevent form submission when the value is missing or invalid, or mark the field as required or invalid via ARIA. | react-aria-components |
value | string | null | undefined | — | The current value (controlled). | @react-types/shared |
Source: packages/ui/src/components/SegmentedButton/SegmentedButton.tsx:113
Material fidelity and web adaptation
- Family
- Segmented buttons
- Provenance
- spec: Material 3 overview · web: Browser and React Aria semantics · adaptation: m3-ui web adaptation
- Compose mapping
- SingleChoiceSegmentedButtonRow · MultiChoiceSegmentedButtonRow · SegmentedButton
- Visual fidelity
- partial: Legacy visual fidelity has not received an explicit reviewed disposition. Current implementation evidence: Implements the Material outlined segmented-button geometry, selected/unselected color and state layers, default selected check mark, optional inactive/selected icon slots, and separate single-choice and multi-choice row primitives.
- Behavior fidelity
- adapted: Single-choice rows use React Aria RadioGroup/Radio semantics while multi-choice segments use independent React Aria Checkbox semantics inside a grouped container. The separate APIs preserve the accessibility model instead of collapsing radio and multi-toggle state into one generic selection contract.
- Semantics fidelity
- adapted: Single-choice rows use React Aria RadioGroup/Radio semantics while multi-choice segments use independent React Aria Checkbox semantics inside a grouped container. The separate APIs preserve the accessibility model instead of collapsing radio and multi-toggle state into one generic selection contract.
- Adaptations
- Single-choice rows use React Aria RadioGroup/Radio semantics while multi-choice segments use independent React Aria Checkbox semantics inside a grouped container. The separate APIs preserve the accessibility model instead of collapsing radio and multi-toggle state into one generic selection contract.
Material provides the connected segmented visual/selection family. Browser semantics deliberately map single-choice to radios and multi-choice to independent checkbox/toggle controls so assistive technologies receive the actual selection model.
Related components
- Radio button — conventional single-choice groups.
- Checkbox — independent selections.
- Button group — grouped actions and connected button selection.