Primer/React

What's new

Design

Interface guidelines Octicons Presentations Command line Mobile Desktop

Build

CSS React ViewComponents

Contribute About

On this page

SegmentedControl

Draft

Use a segmented control to let users select an option from a short list and immediately apply the selection

On this page

Not implemented yet

Examples

Simple

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

<SegmentedControl aria-label="File view">
  <SegmentedControl.Button selected>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 selected 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 selected 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 selected 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 selected 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: 'none'}}>
  <SegmentedControl.Button selected 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: 'none'}}>
  <SegmentedControl.Button selected 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: 'none'}}>
  <SegmentedControl.Button selected 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: 'none'}}>
  <SegmentedControl.Button selected 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 selected>Preview</SegmentedControl.Button>
  <SegmentedControl.Button>Raw</SegmentedControl.Button>
  <SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>

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

In a loading state

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

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

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 selected>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 selected>Preview</SegmentedControl.Button>
    <SegmentedControl.Button>Raw</SegmentedControl.Button>
    <SegmentedControl.Button>Blame</SegmentedControl.Button>
  </SegmentedControl>
</Box>

With a label above and caption below

<FormControl>
  <FormControl.Label id="scLabel-horiz">File view</FormControl.Label>
  <SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
    <SegmentedControl.Button selected>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">File view</FormControl.Label>
  <SegmentedControl aria-labelledby="scLabel-horiz" aria-describedby="scCaption-horiz">
    <SegmentedControl.Button selected>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 something besides the first option selected

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

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

With a selection change handler

<SegmentedControl
  aria-label="File view"
  onChange={selectedIndex => {
    alert(`Segment ${selectedIndex}`)
  }}
>
  <SegmentedControl.Button>Preview</SegmentedControl.Button>
  <SegmentedControl.Button>Raw</SegmentedControl.Button>
  <SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>

<SegmentedControl
  aria-label="File view"
  onChange={selectedIndex => {
    alert(`Segment ${selectedIndex}`)
  }}
>
  <SegmentedControl.Button>Preview</SegmentedControl.Button>
  <SegmentedControl.Button>Raw</SegmentedControl.Button>
  <SegmentedControl.Button>Blame</SegmentedControl.Button>
</SegmentedControl>

Props

SegmentedControl

Name	Type	Description
aria-label	string
aria-labelledby	string
aria-describedby	string
fullWidth	boolean	Whether the control fills the width of its parent
loading	boolean	Whether the selected segment is being calculated
onChange Required	(selectedIndex?: number) => void	The handler that gets called when a segment is selected
variant	{ narrow?: 'hideLabels' \| 'dropdown', regular?: 'hideLabels' \| 'dropdown', wide?: 'hideLabels' \| 'dropdown' }	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

Name	Type	Description
leadingIcon	Component	The leading icon comes before item label
selected	boolean	Whether the segment is selected
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

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
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 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 100% test coverage.

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 has been manually reviewed by the accessibility team and any resulting issues have been addressed.

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.

Edit this page on GitHub

SegmentedControl

Examples

Simple

With icons and labels

With icons only

With labels hidden on smaller viewports

Convert to a dropdown on smaller viewports

Fill width of parent

In a loading state

With a label and caption on the left

With a label above and caption below

With something besides the first option selected

With a selection change handler

Props

SegmentedControl

SegmentedControl.Button

SegmentedControl.IconButton

Status

Alpha

Beta

Stable