SegmentedControl

SegmentedControl may be used to group multiple selections. The controls display the current state and related state.

Create layout to convey clear sense of information hierarchy. When a control is engaged, information below the control should also be updated.

also known as Toggle Group

Figma:

Web:

iOS:

Android:

A11y:

Props

Component props
Name	Type	Default
`items` Required	`$ReadOnlyArray<React.Node>`	-
	Items for selection. Though typically strings, React.Node is accepted to allow for Icons or other custom UI.
`onChange` Required	`({\| event: SyntheticMouseEvent<HTMLButtonElement>, activeIndex: number \|}) => void`	-
	Callback triggered when the user selects an item.
`selectedItemIndex` Required	`number`	-
	Index of element in `items` that is currently selected.
`responsive`	`boolean`	-
	By default, items have equal widths. If this prop is true, the width of an item is based on its content. See the responsive example for more details.

Usage guidelines

When to use

To switch between views within a small area of content, such as a Popover.

When not to use

To switch between views that represent the main content of a surface. Use Tabs instead.
To act as a radio control within a form. Use RadioGroup instead.

Accessibility

Partially ready

Variants

Example

Segmented Control is a naive component, meaning you need to wire any additional behavior when the user clicks on an item. If you'd like the tabs to control hiding or showing content, that state should live in a parent component.

function SegmentedControlExample() {
  const [itemIndex, setItemIndex] = React.useState(0);

  const items = [
    'News',
    'You',
    'Messages',
    <Icon
      icon="pin"
      accessibilityLabel="Pin"
      color="default"
    />,
  ];

  const content = [
    'News content',
    'You content',
    'Messages content',
    'Pins content',
  ];

  return (
    <Flex direction="column" gap={{ column: 2, row: 0 }}>
      <SegmentedControl
        items={items}
        selectedItemIndex={itemIndex}
        onChange={({ activeIndex }) => setItemIndex(activeIndex)}
      />

      <Box borderStyle="shadow" padding={6} rounding={2}>
        <Text>{content[itemIndex]}</Text>
      </Box>
    </Flex>
  );
}

function SegmentedControlExample() {
  const [itemIndex, setItemIndex] = React.useState(0);

  const items = [
    'News',
    'You',
    'Messages',
    <Icon
      icon="pin"
      accessibilityLabel="Pin"
      color="default"
    />,
  ];

  const content = [
    'News content',
    'You content',
    'Messages content',
    'Pins content',
  ];

  return (
    <Flex direction="column" gap={{ column: 2, row: 0 }}>
      <SegmentedControl
        items={items}
        selectedItemIndex={itemIndex}
        onChange={({ activeIndex }) => setItemIndex(activeIndex)}
      />

      <Box borderStyle="shadow" padding={6} rounding={2}>
        <Text>{content[itemIndex]}</Text>
      </Box>
    </Flex>
  );
}

Example: Responsive

Segmented Control can have responsive widths where the width of an item is based on its content.

function SegmentedControlExample() {
  const [item1Index, setItem1Index] = React.useState(0);
  const [item2Index, setItem2Index] = React.useState(0);
  const items = ['Short', 'Really really really long title'];

  return (
    <Flex direction="column" gap={{ column: 6, row: 0 }}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Heading size="400">Equal widths</Heading>
        <SegmentedControl
        items={items}
        onChange={({ activeIndex }) => { setItem1Index(activeIndex); }}
        selectedItemIndex={item1Index}
        />
      </Flex>

      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Heading size="400">Responsive widths</Heading>
        <SegmentedControl
        items={items}
        onChange={({ activeIndex }) => { setItem2Index(activeIndex); }}
        responsive
        selectedItemIndex={item2Index}
        />
      </Flex>
    </Flex>
  );
}

function SegmentedControlExample() {
  const [item1Index, setItem1Index] = React.useState(0);
  const [item2Index, setItem2Index] = React.useState(0);
  const items = ['Short', 'Really really really long title'];

  return (
    <Flex direction="column" gap={{ column: 6, row: 0 }}>
      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Heading size="400">Equal widths</Heading>
        <SegmentedControl
        items={items}
        onChange={({ activeIndex }) => { setItem1Index(activeIndex); }}
        selectedItemIndex={item1Index}
        />
      </Flex>

      <Flex direction="column" gap={{ column: 2, row: 0 }}>
        <Heading size="400">Responsive widths</Heading>
        <SegmentedControl
        items={items}
        onChange={({ activeIndex }) => { setItem2Index(activeIndex); }}
        responsive
        selectedItemIndex={item2Index}
        />
      </Flex>
    </Flex>
  );
}

Component quality checklist

Component quality checklist
Quality item	Status	Status description
Figma Library	Partially ready	Component is live in Figma, however may not be available for all platforms.
Responsive Web	Ready	Component is available in code for web and mobile web.
iOS		Component is not currently available in code for iOS.
Android		Component is not currently available in code for Android.

Edit page on GitHub