SegmentedControl

SegmentedControl is used to pick one choice from a linear set of closely related choices, and immediately apply that selection.

Page navigation navigation

React

readyNot reviewed for a11y

Storybook|Source

Rails

readyReviewed for a11y

Docs|Lookbook|Source

Figma

View in Figma|

React examples

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

import React from 'react'
import {SegmentedControl} from '@primer/react'


export default function Default() {
  const [selectedIndex, setSelectedIndex] = React.useState(0)
  const handleChange = (i: number) => {
    setSelectedIndex(i)
  }


  return (
    <SegmentedControl aria-label="File view" onChange={handleChange}>
      <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>
  )
}

import React from 'react'
import {SegmentedControl} from '@primer/react'

export default function Default() {
  const [selectedIndex, setSelectedIndex] = React.useState(0)
  const handleChange = (i: number) => {
    setSelectedIndex(i)
  }

  return (
    <SegmentedControl aria-label="File view" onChange={handleChange}>
      <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>
  )
}

With leading icons

Guidelines for icons in segments

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

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

Icon-only

Icon-only segment guidlines

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

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

More examples

The previous examples are a curated subset of the full capabilities (such as reponsive behavior) of the SegmentedControl component. For more examples, see the SegmentedControl Storybook stories.

Props

SegmentedControl

Name	Required	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' }` Configure alternative ways to render the control when it gets rendered in tight spaces
size		`'small' \| 'medium'` The size of the buttons
sx		`SystemStyleObject`
ref		`React.RefObject<HTMLDivElement>`

SegmentedControl.Button

Name	Required	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>`

SegmentedControl.IconButton

Name	Required	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.
size		`'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>`
tooltipDirection		`'n' \| 'ne' \| 'e' \| 'se' \| 's' \| 'sw' \| 'w' \| 'nw'`
description		`string` If `description` is provided, we will use a Tooltip to describe the button. Then `aria-label` is used to label the button.