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.

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 RadioButton instead.

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="darkGray"
    />,
  ];

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

  return (
    <Flex direction="column" gap={2}>
      <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="darkGray"
    />,
  ];

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

  return (
    <Flex direction="column" gap={2}>
      <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={6}>
      <Flex direction="column" gap={2}>
        <Heading size="400">Equal widths</Heading>
        <SegmentedControl
        items={items}
        onChange={({ activeIndex }) => { setItem1Index(activeIndex); }}
        selectedItemIndex={item1Index}
        />
      </Flex>

      <Flex direction="column" gap={2}>
        <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={6}>
      <Flex direction="column" gap={2}>
        <Heading size="400">Equal widths</Heading>
        <SegmentedControl
        items={items}
        onChange={({ activeIndex }) => { setItem1Index(activeIndex); }}
        selectedItemIndex={item1Index}
        />
      </Flex>

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

Edit page on GitHub