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:

Responsive:

Adaptive:

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

Default

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.

import { useState } from 'react';
import { Box, Flex, Icon, SegmentedControl, Text } from 'gestalt';

export default function SegmentedControlExample() {
  const [itemIndex, setItemIndex] = useState(0);

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

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

  return (
    <Box padding={8} height="100%">
      <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>
    </Box>
  );
}

Responsive

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

import { useState } from 'react';
import { Box, Flex, Heading, SegmentedControl } from 'gestalt';

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

  return (
    <Box padding={8}>
      <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>
    </Box>
  );
}

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 responds to changing viewport sizes in web and mobile web.

Edit page on GitHub

; Opens a new tab