Primer/React

What's new

Design

Interface guidelines Octicons Presentations Command line Mobile Desktop

Build

CSS React ViewComponents

Contribute About

On this page

SegmentedControl

Alpha

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

On this page

Examples

Uncontrolled (default)

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

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

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 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>

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 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">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 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		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. 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

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	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

1 contributor

Last edited by mperrotti on September 19, 2022

SegmentedControl

Examples

Uncontrolled (default)

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 a label and caption on the left

With a label above and caption below

With something besides the first option selected

Props

SegmentedControl

SegmentedControl.Button

SegmentedControl.IconButton

Status

Alpha

Beta

Stable