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

On this page

This documentation is moving to a new home. Please update any link or bookmark that points to this page. The new content can be found here.

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

<FormControl>
  <FormControl.Label id="scLabel-horiz" as="span">
    File view
  </FormControl.Label>
  <SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
    <SegmentedControl.Button>Raw</SegmentedControl.Button>
    <SegmentedControl.Button>Blame</SegmentedControl.Button>
  </SegmentedControl>
  <FormControl.Caption id="scCaption-horiz">Change the way the file is viewed</FormControl.Caption>
</FormControl>

<FormControl>
  <FormControl.Label id="scLabel-horiz" as="span">
    File view
  </FormControl.Label>
  <SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
    <SegmentedControl.Button>Raw</SegmentedControl.Button>
    <SegmentedControl.Button>Blame</SegmentedControl.Button>
  </SegmentedControl>
  <FormControl.Caption id="scCaption-horiz">Change the way the file is viewed</FormControl.Caption>
</FormControl>

With a label and caption on the left

<Box display="flex">
  <Box flexGrow={1}>
    <Text fontSize={2} fontWeight="bold" id="scLabel-vert" display="block">
      File view
    </Text>
    <Text color="fg.subtle" fontSize={1} id="scCaption-vert" display="block">
      Change the way the file is viewed
    </Text>
  </Box>
  <SegmentedControl aria-labelledby="scLabel-vert" aria-describedby="scCaption-vert">
    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
    <SegmentedControl.Button>Raw</SegmentedControl.Button>
    <SegmentedControl.Button>Blame</SegmentedControl.Button>
  </SegmentedControl>
</Box>

<Box display="flex">
  <Box flexGrow={1}>
    <Text fontSize={2} fontWeight="bold" id="scLabel-vert" display="block">
      File view
    </Text>
    <Text color="fg.subtle" fontSize={1} id="scCaption-vert" display="block">
      Change the way the file is viewed
    </Text>
  </Box>
  <SegmentedControl aria-labelledby="scLabel-vert" aria-describedby="scCaption-vert">
    <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
    <SegmentedControl.Button>Raw</SegmentedControl.Button>
    <SegmentedControl.Button>Blame</SegmentedControl.Button>
  </SegmentedControl>
</Box>

Controlled

const Controlled = () => {
  const [selectedIndex, setSelectedIndex] = React.useState(0)

  const handleSegmentChange = selectedIndex => {
    setSelectedIndex(selectedIndex)
  }

  return (
    <SegmentedControl aria-label="File view" onChange={handleSegmentChange}>
      <SegmentedControl.Button selected={selectedIndex === 0}>Preview</SegmentedControl.Button>
      <SegmentedControl.Button selected={selectedIndex === 1}>Raw</SegmentedControl.Button>
      <SegmentedControl.Button selected={selectedIndex === 2}>Blame</SegmentedControl.Button>
    </SegmentedControl>
  )
}

render(Controlled)

const Controlled = () => {
  const [selectedIndex, setSelectedIndex] = React.useState(0)

  const handleSegmentChange = selectedIndex => {
    setSelectedIndex(selectedIndex)
  }

  return (
    <SegmentedControl aria-label="File view" onChange={handleSegmentChange}>
      <SegmentedControl.Button selected={selectedIndex === 0}>Preview</SegmentedControl.Button>
      <SegmentedControl.Button selected={selectedIndex === 1}>Raw</SegmentedControl.Button>
      <SegmentedControl.Button selected={selectedIndex === 2}>Blame</SegmentedControl.Button>
    </SegmentedControl>
  )
}

render(Controlled)

Small

<SegmentedControl aria-label="File view" size="small">
  <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
  <SegmentedControl.Button>Raw</SegmentedControl.Button>
  <SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>

<SegmentedControl aria-label="File view" size="small">
  <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
  <SegmentedControl.Button>Raw</SegmentedControl.Button>
  <SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>

With icons and labels

<SegmentedControl aria-label="File view">
  <SegmentedControl.Button defaultSelected leadingIcon={EyeIcon}>
    Preview
  </SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={FileCodeIcon}>Raw</SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={PeopleIcon}>Blame</SegmentedControl.Button>
</SegmentedControl>

<SegmentedControl aria-label="File view">
  <SegmentedControl.Button defaultSelected leadingIcon={EyeIcon}>
    Preview
  </SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={FileCodeIcon}>Raw</SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={PeopleIcon}>Blame</SegmentedControl.Button>
</SegmentedControl>

With icons only

<SegmentedControl aria-label="File view">
  <SegmentedControl.IconButton defaultSelected icon={EyeIcon} aria-label="Preview" />
  <SegmentedControl.IconButton icon={FileCodeIcon} aria-label="Raw" />
  <SegmentedControl.IconButton icon={PeopleIcon} aria-label="Blame" />
</SegmentedControl>

<SegmentedControl aria-label="File view">
  <SegmentedControl.IconButton defaultSelected icon={EyeIcon} aria-label="Preview" />
  <SegmentedControl.IconButton icon={FileCodeIcon} aria-label="Raw" />
  <SegmentedControl.IconButton icon={PeopleIcon} aria-label="Blame" />
</SegmentedControl>

With labels hidden on smaller viewports

<SegmentedControl aria-label="File view" variant={{narrow: 'hideLabels', regular: 'default'}}>
  <SegmentedControl.Button defaultSelected leadingIcon={EyeIcon}>
    Preview
  </SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={FileCodeIcon}>Raw</SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={PeopleIcon}>Blame</SegmentedControl.Button>
</SegmentedControl>

<SegmentedControl aria-label="File view" variant={{narrow: 'hideLabels', regular: 'default'}}>
  <SegmentedControl.Button defaultSelected leadingIcon={EyeIcon}>
    Preview
  </SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={FileCodeIcon}>Raw</SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={PeopleIcon}>Blame</SegmentedControl.Button>
</SegmentedControl>

<SegmentedControl aria-label="File view" variant={{narrow: 'dropdown', regular: 'default'}}>
  <SegmentedControl.Button defaultSelected leadingIcon={EyeIcon}>
    Preview
  </SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={FileCodeIcon}>Raw</SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={PeopleIcon}>Blame</SegmentedControl.Button>
</SegmentedControl>

<SegmentedControl aria-label="File view" variant={{narrow: 'dropdown', regular: 'default'}}>
  <SegmentedControl.Button defaultSelected leadingIcon={EyeIcon}>
    Preview
  </SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={FileCodeIcon}>Raw</SegmentedControl.Button>
  <SegmentedControl.Button leadingIcon={PeopleIcon}>Blame</SegmentedControl.Button>
</SegmentedControl>

Fill width of parent

<SegmentedControl fullWidth aria-label="File view">
  <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
  <SegmentedControl.Button>Raw</SegmentedControl.Button>
  <SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>

<SegmentedControl fullWidth aria-label="File view">
  <SegmentedControl.Button defaultSelected>Preview</SegmentedControl.Button>
  <SegmentedControl.Button>Raw</SegmentedControl.Button>
  <SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>

With something besides the first option selected

<SegmentedControl aria-label="File view">
  <SegmentedControl.Button>Preview</SegmentedControl.Button>
  <SegmentedControl.Button defaultSelected>Raw</SegmentedControl.Button>
  <SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>

<SegmentedControl aria-label="File view">
  <SegmentedControl.Button>Preview</SegmentedControl.Button>
  <SegmentedControl.Button defaultSelected>Raw</SegmentedControl.Button>
  <SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>

Props

SegmentedControl

Name	Type	Default	Description
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
ref	React.RefObject<HTMLDivElement>		A ref to the element rendered by this component.

SegmentedControl.Button

Name	Type	Description
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
ref	React.RefObject<HTMLButtonElement>	A ref to the element rendered by this component.

SegmentedControl.IconButton

Name	Type	Description
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
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.