Components

Button - Segmented

Also known as: Segmented button, Segmented control

Don't use: proposed

USWDS v3

The button segmented component presents a set of 2-4 closely related options or filters in a compact, horizontal container. It allows users to switch between different views or sort/filter a single set of content. One option is always active.

Examples

Web

This component has not yet been built for the web.

App

Usage

Additional guidance for VA

When to use a Button - Segmented

Use a Button - Segmented for filtering, sorting, or switching views of a single set of data. The options modify the content on the current page without navigating away. It functions like a set of radio buttons where selecting one option automatically deselects the previous one.

Best for: 2-4 mutually exclusive choices.
Example: Filtering a list of appointments by “Upcoming” and “Past.”
Example: Switching a view from a “List” to a “Grid.”

When to consider something else

If you need to group content that is dissimilar.
If you need to enable actions — such as adding, removing, or editing content.
If it needs to be accompanied by any other controls or a title if used in the top navigation bar.

Use Tabs for navigation between distinct, related pages or content sections. Each tab typically corresponds to a unique URL.

Example: Navigating between “Inbox,” “Sent,” and “Archived” folders.

Behavior

A segmented control consists of a horizontal set of 2-4 segments, each of which functions as a button. One option is always selected. The component does not scroll horizontally.

Placement

Web

A Button - Segmented is typically placed directly above the content it controls and modifies that content using client-side logic without a page reload.

App

The component is often integrated into the top navigation bar (or just below it) and should not be placed in a bottom toolbar. It is static and does not scroll horizontally.

Instances of this component in production

Correct Use

Appointments: Using an “Upcoming/Past” control to filter a list of appointments.
Claims: Using an “Active/Closed” control to filter a list of claims.

Incorrect Use

Claims: Using a control to switch between “Status” and “Details.” This groups dissimilar content and should be handled with a different component, like Tabs.

Content considerations

Keep labels concise. Aim for single-word labels (e.g., “List,” “Grid,” “Upcoming,” “Past”). If you need more than one word, it may indicate that the options are not closely related enough, and a different component might be more suitable.
Avoid dissimilar content. Do not use a Segmented Button to group unrelated items. The purpose is to filter or change the view of a single data set.
Provide context. Ensure the labels on the segments clearly differentiate the content that will be displayed below.

Accessibility considerations

Ensuring the component is accessible is critical on all platforms.

Web

Name: The purpose of each button must be clear and match its visible label.
Role: Buttons should identify as “toggle buttons” to the screen reader (e.g. VoiceOver) and announce the appropriate action (e.g., Apple’s Voiceover’s “to select press Control-Option-Space”).
State: The component must clearly announce its state, such as “Selected” for the active button. Navigation: When you navigate to the first button and use the tab key to move forward and shift+tab to move back between the second or subsequent buttons. Use the tab key to exit the group and into other interactive elements.
Mind target size. We follow the WCAG 2.2 Target Size - Level AAA criteria which states:

“The size of the target for pointer inputs is at least 44 by 44 CSS pixels…”

App

For native mobile apps, the component must correctly report its properties to the operating system’s accessibility services.

Name: The purpose of each button must be clear and match its visible label.
Role: It should identify as a “button” to the screen reader (e.g., iOS VoiceOver) and announce the appropriate action (e.g., Android TalkBack’s “double tap to activate”).
State: The component must clearly announce its state, such as “Selected” for the active button.
Font Scaling: In some native implementations (like Apple’s), this component may intentionally ignore the user’s font scaling settings to maintain a consistent layout in the navigation bar. This is a design trade-off where component integrity is prioritized over text resizing.

Reference Segmented Control / Tab - Native app accessibility checklist - MagentaA11y

Tabs

Component checklist

Maturity

Guidance: Examples, usage, code usage, content considerations, and accessibility considerations are all complete.
Research: VFS team conducted research on this component which is linked from this page.
Stability: Component has been in production for more than 3 months with no significant issues found.
Adoption: Multiple teams have adopted this component.

Accessibility

For more information on each category, see Accessibility testing for design system components.

Last audit date: 2025-06-16

Code review: Pass

Readability: Pass

Automated scans: Pass

Use of color: Pass

Text resizing, zoom, and magnification: Pass

Screen readers: Pass

Input and interaction methods: Pass

Code assets

Variations: Storybook includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component depicted in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.
Internationalization: Describes i18n attributes.

Visual assets

Variations: Figma library includes all variations (style, size, orientation, optional iconography, selection, error state, etc.)
Responsive: Component designed to work in all responsive breakpoints.
Interactive states: Includes all interactive states that are applicable (hover, active, focus, keyboard focus, disabled).
Tokens: All design attributes (color, typography, layout, etc.) are available as tokens.

88% complete (15 of 17)

Legend:

Complete
Incomplete
Not applicable

Edit this page in GitHub (Permissions required)

Last updated: Jun 26, 2025