SegmentedControl

Use a segmented control to let users select an option from a short list and immediately apply the selection
  • Alpha
  • Not reviewed for accessibility

A SegmentedControl should not be used in a form as a replacement for something like a RadioGroup or Select. See the Accessibility section of the SegmentedControl interface guidelines for more details.

Examples

With a label above and caption below

With a label and caption on the left

Controlled

Small

With icons and labels

With icons only

With labels hidden on smaller viewports

Convert to a dropdown on smaller viewports

Fill width of parent

With something besides the first option selected

Props

SegmentedControl

NameTypeDefaultDescription
aria-label
string
aria-labelledby
string
aria-describedby
string
fullWidth
| boolean | { narrow?: boolean regular?: boolean wide?: boolean }
Whether the control fills the width of its parent
onChange
(selectedIndex?: number) => void
The handler that gets called when a segment is selected
variant
| 'default' | { narrow?: 'hideLabels' | 'dropdown' | 'default' regular?: 'hideLabels' | 'dropdown' | 'default' wide?: 'hideLabels' | 'dropdown' | 'default' }
'default'Configure alternative ways to render the control when it gets rendered in tight spaces
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.
ref
React.RefObject<HTMLDivElement>
A ref to the element rendered by this component.

SegmentedControl.Button

NameTypeDefaultDescription
leadingIcon
Component
The leading icon comes before item label
selected
boolean
Whether the segment is selected. This is used for controlled SegmentedControls, and needs to be updated using the onChange handler on SegmentedControl.
defaultSelected
boolean
Whether the segment is selected. This is used for uncontrolled SegmentedControls to pick one SegmentedControlButton that is selected on the initial render.
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.
ref
React.RefObject<HTMLButtonElement>
A ref to the element rendered by this component.

SegmentedControl.IconButton

NameTypeDefaultDescription
aria-label Required
string
icon Required
Component
The icon that represents the segmented control item
selected
boolean
Whether the segment is selected. This is used for controlled SegmentedControls, and needs to be updated using the onChange handler on SegmentedControl.
selected
'small' | 'medium'
The size of the buttons
defaultSelected
boolean
Whether the segment is selected. This is used for uncontrolled SegmentedControls to pick one SegmentedControlButton that is selected on the initial render.
sx
SystemStyleObject
Style overrides to apply to the component. See also overriding styles.
ref
React.RefObject<HTMLButtonElement>
A ref to the element rendered by this component.

Status

Alpha

  • Component props and basic example usage of the component are documented on primer.style/react.
  • Component does not have any unnecessary third-party dependencies.
  • Component can adapt to different themes.
  • Component can adapt to different screen sizes.
  • Component has robust unit test coverage (100% where achievable).
  • Component has visual regression coverage of its default and interactive states.
  • Component does not introduce any axe violations.
  • Component has been manually reviewed by the accessibility team and any resulting issues have been addressed.

Beta

  • Component is used in a production application.
  • Common usage examples are documented on primer.style/react.
  • Common usage examples are documented in storybook stories.
  • Component has been reviewed by a systems designer and any resulting issues have been addressed.
  • Component does not introduce any performance regressions.

Stable

  • Component API has been stable with no breaking changes for at least one month.
  • Feedback on API usability has been sought from developers using the component and any resulting issues have been addressed.
  • Component has corresponding design guidelines documented in the interface guidelines.
  • Component has corresponding Figma component in the Primer Web library.
  • Tooling (such as linters, codemods, etc.) exists to prevent further use of alternatives.