Segmented Button

A Segmented button is a linear set of two or more segments, each of which presents a mutually exclusive button.

Use the Segmented Button to group several related buttons of which only one can be active at a time. This component may be used to switch between related modes, eg. display as table/chart, or to toggle different Panels in the application (eg. preview/edit). When using a Segmented Button, the actions should all be related, otherwise, separate buttons should be used.

Example

Live Editor

function controlledSegmentedButton() { const [value, setValue] = useState('shanghai'); const cities = [ { value: 'shanghai', label: 'Shanghai' }, { value: 'moscow', label: 'Moscow' }, { value: 'berlin', label: 'Berlin' }, { value: 'paris', label: 'Paris' } ]; return ( <SegmentedButton items={cities} value={value} onChange={event => setValue(event.target.value)} /> ); }

function controlledSegmentedButton() {
  const [value, setValue] = useState('shanghai');
  const cities = [
    { value: 'shanghai', label: 'Shanghai' },
    { value: 'moscow', label: 'Moscow' },
    { value: 'berlin', label: 'Berlin' },
    { value: 'paris', label: 'Paris' }
  ];

  return (
    <SegmentedButton
      items={cities}
      value={value}
      onChange={event => setValue(event.target.value)}
    />
  );
}

Result

Loading...

Usage Rules

Don’t:

• Combine segments with and without icon in one Segmented Button

Variants

Label

You can add a label to let users know what the SegmentedButton is for and also add extra piece of information to the label by including a tooltip.

Live Editor

function controlledSegmentedButton() { const [value, setValue] = useState('shanghai'); const cities = [ { value: 'shanghai', label: 'Shanghai' }, { value: 'moscow', label: 'Moscow' }, { value: 'berlin', label: 'Berlin' }, { value: 'paris', label: 'Paris' } ]; return ( <SegmentedButton label="Label" labelIconTooltip={{ content: 'hello', position: 'top' }} items={cities} value={value} onChange={event => setValue(event.target.value)} /> ); }

function controlledSegmentedButton() {
  const [value, setValue] = useState('shanghai');
  const cities = [
    { value: 'shanghai', label: 'Shanghai' },
    { value: 'moscow', label: 'Moscow' },
    { value: 'berlin', label: 'Berlin' },
    { value: 'paris', label: 'Paris' }
  ];

  return (
    <SegmentedButton
      label="Label"
      labelIconTooltip={{
        content: 'hello',
        position: 'top'
      }}
      items={cities}
      value={value}
      onChange={event => setValue(event.target.value)}
    />
  );
}

Result

Loading...

Icon

Live Editor

function controlledSegmentedButton() { const [value, setValue] = useState('shanghai'); const cities = [ { value: 'shanghai', label: 'Shanghai', iconOnly: true, iconName: 'ChevronDown' }, { value: 'moscow', label: 'Moscow', iconOnly: true, iconName: 'Check' }, { value: 'berlin', label: 'Berlin', iconOnly: true, iconName: 'Cross' }, { value: 'paris', label: 'Paris', iconOnly: true, iconName: 'Search' } ]; return ( <SegmentedButton items={cities} value={value} onChange={event => setValue(event.target.value)} /> ); }

function controlledSegmentedButton() {
  const [value, setValue] = useState('shanghai');
  const cities = [
    {
      value: 'shanghai',
      label: 'Shanghai',
      iconOnly: true,
      iconName: 'ChevronDown'
    },
    { value: 'moscow', label: 'Moscow', iconOnly: true, iconName: 'Check' },
    { value: 'berlin', label: 'Berlin', iconOnly: true, iconName: 'Cross' },
    { value: 'paris', label: 'Paris', iconOnly: true, iconName: 'Search' }
  ];

  return (
    <SegmentedButton
      items={cities}
      value={value}
      onChange={event => setValue(event.target.value)}
    />
  );
}

Result

Loading...

Label and Icon

Live Editor

function controlledSegmentedButton() { const [value, setValue] = useState('shanghai'); const cities = [ { value: 'shanghai', label: 'Shanghai' }, { value: 'moscow', label: 'Moscow', iconName: 'Check' }, { value: 'berlin', label: 'Berlin' }, { value: 'paris', label: 'Paris', iconName: 'Cross' } ]; return ( <SegmentedButton items={cities} value={value} onChange={event => setValue(event.target.value)} /> ); }

function controlledSegmentedButton() {
  const [value, setValue] = useState('shanghai');
  const cities = [
    { value: 'shanghai', label: 'Shanghai' },
    { value: 'moscow', label: 'Moscow', iconName: 'Check' },
    { value: 'berlin', label: 'Berlin' },
    { value: 'paris', label: 'Paris', iconName: 'Cross' }
  ];

  return (
    <SegmentedButton
      items={cities}
      value={value}
      onChange={event => setValue(event.target.value)}
    />
  );
}

Result

Loading...

Size

The Segmented button comes in two sizes: small and medium.

Live Editor

function controlledSegmentedButton() { const [value1, setValue1] = useState('shanghai'); const [value2, setValue2] = useState('shanghai'); const cities = [ { value: 'shanghai', label: 'Shanghai' }, { value: 'moscow', label: 'Moscow' }, { value: 'berlin', label: 'Berlin' }, { value: 'paris', label: 'Paris' } ]; return ( <> <SegmentedButton items={cities} size="small" value={value1} onChange={event => setValue1(event.target.value)} /> <SegmentedButton items={cities} size="medium" value={value2} onChange={event => setValue2(event.target.value)} /> </> ); }

function controlledSegmentedButton() {
  const [value1, setValue1] = useState('shanghai');
  const [value2, setValue2] = useState('shanghai');
  const cities = [
    { value: 'shanghai', label: 'Shanghai' },
    { value: 'moscow', label: 'Moscow' },
    { value: 'berlin', label: 'Berlin' },
    { value: 'paris', label: 'Paris' }
  ];

  return (
    <>
      <SegmentedButton
        items={cities}
        size="small"
        value={value1}
        onChange={event => setValue1(event.target.value)}
      />
      <SegmentedButton
        items={cities}
        size="medium"
        value={value2}
        onChange={event => setValue2(event.target.value)}
      />
    </>
  );
}

Result

Loading...

Tooltip

note

Make sure to pass an empty element on children key at the Tooltip object when using this option, as on the example below.

Live Editor

function controlledSegmentedButton() { const [value, setValue] = useState('calendar'); const options = [ { value: 'calendar', label: 'Calendar', iconOnly: true, iconName: 'Calendar', tooltip: { content: 'Calendar', children: <></> } }, { value: 'data', label: 'Data', iconOnly: true, iconName: 'Data', tooltip: { content: 'Data', children: <></> } } ]; return ( <SegmentedButton items={options} value={value} onChange={event => setValue(event.target.value)} /> ); }

function controlledSegmentedButton() {
  const [value, setValue] = useState('calendar');
  const options = [
    {
      value: 'calendar',
      label: 'Calendar',
      iconOnly: true,
      iconName: 'Calendar',
      tooltip: { content: 'Calendar', children: <></> }
    },
    {
      value: 'data',
      label: 'Data',
      iconOnly: true,
      iconName: 'Data',
      tooltip: { content: 'Data', children: <></> }
    }
  ];

  return (
    <SegmentedButton
      items={options}
      value={value}
      onChange={event => setValue(event.target.value)}
    />
  );
}

Result

Loading...

Props

SegmentedButton

Name	Type	Default
onChange * The handler will be called on a new selection. We pass this callback to the HTML input element. You can access the value of a newly selected segment with event.target.value (string)	(event: ChangeEvent<HTMLInputElement>) => void	—
items * Array of Segment items. See props of this component below	SegmentItemType[]	—
label The visual label of the SegmentedButton	string	—
labelIconTooltip The labelIconTooltip content can either be pure text or any rich content wrapped in a React component The labelIconTooltip content will be shown when hovering the label icon. The labelIconTooltip position is used to define the positioning of the tooltip When the labelIconTooltip content is not provided, the label icon will be not shown.	Omit<TooltipProps, "children">	—
size The size of the Segmented Button	"small" | "medium"	"medium"
value Value of checked segment	string	—
id Internally, this component uses a random id. We use it to associate an input with a label element. As the random id might break snapshot tests it can be overridden by setting an explicit id.	string	—
css Add custom styles to this component. Use with caution. Learn more here: Link	SupportedStyleAttributes	—
inputFieldCss	SupportedStyleAttributes	—
data-{foo} Data attributes can be used by testing libraries to retrieve components or assert their existence	string	—
* - the prop is required.

Object structure of the items prop

Name	Type	Default
label * Label of the segment	string	—
value * Native HTML attribute: Link	string | number	—
iconName Name of the Icon that would appear on the right. Please refer to the full list here: Link	"AddValue" | "AppGrid" | "ArrowCircleLeft" | "ArrowCircleRight" | "ArrowDown" | "ArrowDownLeft" | "A...	—
iconOnly If the visual label should be hidden	boolean	false
id Native HTML attribute: Link . Internally, this component uses a random id. We use it to associate an input with a label element. As the random id might break snapshot tests it can be overridden by setting an explicit id.	string	—
tooltip Add a tooltip when hovering a specific segmented button. More here: Link	TooltipProps	—
dataTestId A test id to be used by testing libraries. It will be added as a "data-testid" attribute on the segment.	string	—
* - the prop is required.

Related Components

• Radio
• Tooltip