Segmented button group

The guideline content on this page is synced with Figma and can be used as a source of truth. Open in Figma

Segmented button group displays multiple related actions stacked or in a horizontal row to help with arrangement and spacing. The buttons are displayed as a horizontal group of buttons, where only one option can be selected at a time.

Anatomy

Selected content tab
Content tab
Label text
Container

With icon

An icon should be used in a segmented control when it provides quick, universal understanding of the option and can replace or supplement text for clarity and space efficiency.

Example
HTML

development/documentation/docs/segmented-button-group/examples/segmented-with-icon.html

<div class="btn-group btn-group-tabs" role="group" aria-label="Segmented button with icon">
	<button type="button" class="btn demo-br-0"><span class="spirisicon spirisicon-sm spirisicon-file" aria-hidden="true"></span> Segmented button</button>
</div>

States

This component has the following states:

Default
Hover
Focus
Selected
Disabled

Example
HTML

States

development/documentation/docs/segmented-button-group/examples/segmented-states.html

<p class="mb-8"><b>States</b></p>
<div class="d-flex gap-16 flex-wrap">
	<div class="btn-group btn-group-tabs" role="group" aria-label="Enabled state">
		<button type="button" class="btn demo-br-0">Enabled</button>
	</div>
	<div class="btn-group btn-group-tabs" role="group" aria-label="Hover state">
		<button type="button" class="btn hover demo-br-0">Hover</button>
	</div>
	<div class="btn-group btn-group-tabs" role="group" aria-label="Pressed state">
		<button type="button" class="btn pressed demo-br-0" aria-pressed="true">Pressed</button>
	</div>
	<div class="btn-group btn-group-tabs" role="group" aria-label="Focused state">
		<button type="button" class="btn focus demo-br-0">Focused</button>
	</div>
	<div class="btn-group btn-group-tabs" role="group" aria-label="Selected state">
		<button type="button" class="btn active demo-br-0" aria-selected="true">Selected</button>
	</div>
	<div class="btn-group btn-group-tabs" role="group" aria-label="Selected hover state">
		<button type="button" class="btn active hover demo-br-0">Selected hover</button>
	</div>
	<div class="btn-group btn-group-tabs" role="group" aria-label="Disabled state">
		<button type="button" class="btn demo-br-0" disabled>Disabled</button>
	</div>
</div>

Usage

Information

When a user clicks an option, it becomes active, and the previously selected option becomes inactive. Segmented buttons are visually connected, typically contained within a single border or container.

The primary function is to enable users to switch between different views of the same content, sort data, or choose a single setting from a limited set of options.

The number of segments should be small, typically 2 to 5, to prevent the component from becoming too wide or overwhelming for the user.

The effect of selecting a button should be immediate and obvious, with no need for a “Submit” or “Apply” button.

Example
HTML

development/documentation/docs/segmented-button-group/examples/segmented-default.html

<div class="btn-group btn-group-tabs" role="group" aria-label="Segmented button group">
	<button type="button" class="btn">Button</button>
	<button type="button" class="btn">Button</button>
	<button type="button" class="btn active" aria-selected="true">Button</button>
	<button type="button" class="btn">Button</button>
</div>

Badge

You can display a number next to the text in the segmented button. This feature can be toggled on or off in the settings menu located in the top right corner of Figma.

Example
HTML

development/documentation/docs/segmented-button-group/examples/segmented-with-badge.html

<!-- Badge background uses --surface-light (overridden in documentation CSS) -->
<div class="btn-group btn-group-tabs" role="group" aria-label="Segmented button group with badges">
	<button type="button" class="btn">Button <span class="badge">2</span></button>
	<button type="button" class="btn">Button</button>
	<button type="button" class="btn active" aria-selected="true">Button</button>
	<button type="button" class="btn">Button</button>
</div>

Placement

Segmented button groups are positioned within the sub-header region, situated between the page title and the primary data container.

This placement establishes a definitive visual hierarchy, designating the component as a high-level view controller that governs the scope of the underlying content.

Segmented button group placement within sub-header region

Accessibility

Keyboard interaction

All components should be reachable via TAB and SHIFT+TAB keys.

Example
HTML

development/documentation/docs/segmented-button-group/examples/segmented-keyboard.html

<div class="btn-group btn-group-tabs" role="group" aria-label="Segmented button focused state">
	<button type="button" class="btn focus demo-br-0"><span class="spirisicon spirisicon-sm spirisicon-file" aria-hidden="true"></span> Focused</button>
</div>

Best practices

development/documentation/docs/segmented-button-group/examples/best-practice-short-text-do.html

<div class="btn-group btn-group-tabs" role="group" aria-label="Short text do example">
	<button type="button" class="btn active" aria-selected="true">Day</button>
	<button type="button" class="btn">Week</button>
	<button type="button" class="btn">Year</button>
</div>

Keep labels short and concise. If a label is too long for a segmented control, use a different component like a dropdown or quick filter.

Example
HTML

development/documentation/docs/segmented-button-group/examples/best-practice-short-text-dont.html

<div class="btn-group btn-group-tabs" role="group" aria-label="Short text don't example">
	<button type="button" class="btn active" aria-selected="true">See all the last 24 hours</button>
	<button type="button" class="btn">See all this week</button>
	<button type="button" class="btn">See all this year (2025)</button>
</div>

Don't

Don’t use long labels.

Consistent size

Example
HTML

development/documentation/docs/segmented-button-group/examples/best-practice-consistent-do.html

<div class="btn-group btn-group-tabs" role="group" aria-label="Consistent size do example">
	<button type="button" class="btn">First</button>
	<button type="button" class="btn active" aria-selected="true">Second</button>
	<button type="button" class="btn">Third</button>
</div>

Keep button widths consistent across all segments.

Example
HTML

development/documentation/docs/segmented-button-group/examples/best-practice-consistent-dont.html

<div class="btn-group btn-group-tabs" role="group" aria-label="Consistent size don't example">
	<button type="button" class="btn">First</button>
	<button type="button" class="btn active" aria-selected="true">A much longer second button</button>
	<button type="button" class="btn">Third</button>
</div>

Don't

Don’t change the width of individual buttons.

Specs

Segmented button group specifications showing dimensions and spacing

Developer reference

The following sections describe supported functionality that is not part of the Figma design specification.

Design

Default

Add .btn-group-tabs class to the .btn-group to create segmented controls. Use .active on the selected button and aria-selected="true" for accessibility.

Example
HTML

development/documentation/docs/segmented-button-group/examples/segmented-default.html

<div class="btn-group btn-group-tabs" role="group" aria-label="Segmented button group">
	<button type="button" class="btn">Button</button>
	<button type="button" class="btn">Button</button>
	<button type="button" class="btn active" aria-selected="true">Button</button>
	<button type="button" class="btn">Button</button>
</div>

Small size

Add .btn-group-tabs-sm class to the wrapper for a smaller variant.

Example
HTML

development/documentation/docs/segmented-button-group/examples/segmented-small.html

<div class="btn-group btn-group-tabs btn-group-tabs-sm" role="group" aria-label="Segmented button group small">
	<button type="button" class="btn active" aria-selected="true">Button</button>
	<button type="button" class="btn">Button</button>
	<button type="button" class="btn">Button</button>
</div>

Disabled

Add the disabled attribute to individual buttons to disable them.

Example
HTML

Single disabled button

All disabled

development/documentation/docs/segmented-button-group/examples/segmented-disabled.html

<p class="mb-8"><b>Single disabled button</b></p>
<div class="btn-group btn-group-tabs" role="group" aria-label="Segmented button group with disabled button">
	<button type="button" class="btn" disabled>Disabled</button>
	<button type="button" class="btn">Button</button>
	<button type="button" class="btn active" aria-selected="true">Button</button>
</div>

<p class="mb-8 mt-24"><b>All disabled</b></p>
<div class="btn-group btn-group-tabs" role="group" aria-label="Segmented button group all disabled">
	<button type="button" class="btn" disabled>Button</button>
	<button type="button" class="btn" disabled>Button</button>
	<button type="button" class="btn" disabled>Button</button>
</div>

Legacy button groups

Button groups

Deprecated in v2.3

The default .btn-group without .btn-group-tabs is deprecated and will be removed in v3.0. Use .btn-group.btn-group-tabs instead.

Example
HTML

Default

Primary

development/documentation/docs/segmented-button-group/examples/button-groups.html

<p class="mb-8"><b>Default</b></p>
<div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups">
	<div class="btn-group demo-with-states" role="group" aria-label="Button group">
		<button type="button" class="btn">Left</button>
		<button type="button" class="btn">Middle</button>
		<button type="button" class="btn active">Right</button>
	</div>
</div>

<p class="mb-8 mt-24"><b>Primary</b></p>
<div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups">
	<div class="btn-group btn-group-primary demo-with-states" role="group" aria-label="Button group with alternative style">
		<button type="button" class="btn">Left</button>
		<button type="button" class="btn">Middle</button>
		<button type="button" class="btn active" aria-selected="true">Right</button>
	</div>
</div>

With dropdowns

Deprecated in v2.3

Dropdowns inside button groups are deprecated and will be removed in v3.0. Use a standalone dropdown component instead.

Example
HTML

Small

Regular

Large

development/documentation/docs/segmented-button-group/examples/button-groups-dropdowns.html

<p class="mb-8 mt-24"><b>Small</b></p>
<div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups">
    <div class="btn-group btn-group-sm" role="group" aria-label="Button group with nested dropdown">
        <button type="button" class="btn">Left</button>
        <div class="dropdown">
            <button type="button" id="btnGroupDrop3" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown</button>
            <div class="dropdown-menu" role="menu" aria-expanded="false" aria-hidden="true" aria-labelledby="btnGroupDrop3">
                <button type="button" class="dropdown-item">Item 1</button>
                <button type="button" class="dropdown-item disabled" tabindex="-1" aria-disabled="true">Item 2</button>
                <button type="button" class="dropdown-item">Item 3, with a looooong label</button>
                <button type="button" class="dropdown-item active">Item 4</button>
                <button type="button" class="dropdown-item">Item 5</button>
            </div>
        </div>
        <button type="button" class="btn">Right</button>
    </div>
</div>

<p class="mb-8"><b>Regular</b></p>
<div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups">
    <div class="btn-group" role="group" aria-label="Button group with nested dropdown">
        <div class="dropdown">
            <button type="button" id="btnGroupDrop1" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown</button>
            <div class="dropdown-menu" role="menu" aria-expanded="false" aria-hidden="true" aria-labelledby="btnGroupDrop1">
                <button type="button" class="dropdown-item">Item 1</button>
                <button type="button" class="dropdown-item disabled" tabindex="-1" aria-disabled="true">Item 2</button>
                <button type="button" class="dropdown-item">Item 3, with a looooong label</button>
                <button type="button" class="dropdown-item active">Item 4</button>
                <button type="button" class="dropdown-item">Item 5</button>
            </div>
        </div>
        <button type="button" class="btn">Middle</button>
        <button type="button" class="btn">Right</button>
    </div>
</div>

<p class="mb-8 mt-24"><b>Large</b></p>
<div class="btn-toolbar" role="toolbar" aria-label="Toolbar with button groups">
    <div class="btn-group btn-group-lg" role="group" aria-label="Button group with nested dropdown">
        <button type="button" class="btn">Left</button>
        <div class="dropdown">
            <button type="button" id="btnGroupDrop2" class="btn dropdown-toggle" data-toggle="dropdown" aria-haspopup="true" aria-expanded="false">Dropdown</button>
            <div class="dropdown-menu" role="menu" aria-expanded="false" aria-hidden="true" aria-labelledby="btnGroupDrop2">
                <button type="button" class="dropdown-item">Item 1</button>
                <button type="button" class="dropdown-item disabled" tabindex="-1" aria-disabled="true">Item 2</button>
                <button type="button" class="dropdown-item">Item 3, with a looooong label</button>
                <button type="button" class="dropdown-item active">Item 4</button>
                <button type="button" class="dropdown-item">Item 5</button>
            </div>
        </div>
        <button type="button" class="btn">Right</button>
    </div>
</div>

Vertical button groups

Deprecated in v2.3

Vertical button groups are deprecated and will be removed in v3.0. Use segmented button groups (.btn-group.btn-group-tabs) for horizontal selection instead.

Example
HTML

development/documentation/docs/segmented-button-group/examples/vertical-button-groups.html

<div class="btn-group-vertical demo-with-states" role="group" aria-label="Button group">
    <button type="button" class="btn">Top</button>
    <button type="button" class="btn disabled" tabindex="-1" aria-disabled="true">Middle</button>
    <button type="button" class="btn active" aria-selected="true">Middle</button>
    <button type="button" class="btn">Middle</button>
</div>