Components

Button - Segmented

Also known as: Segmented button, Segmented control

Use with caution: candidate

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

Default

View va-button-segmented–default in Storybook

Selected item

View va-button-segmented–selected-item in Storybook

App

Usage

Additional guidance for VA

When to use a Button - Segmented

Use a Segmented Button 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 is used in the top navigation bar alongside other controls or a title.

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 Segmented Button 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.

Code usage

Attributes and Properties

Property Attribute Type Default Description

buttons ButtonItem[] An array of objects defining the labels and values for each button. The recommended structure is: `{ label: string, value?: string }`, with the `label` property being required. The `value` property is optional and can be used to store additional information about the button. The maximum number of buttons allowed is four.

disableAnalytics disable-analytics boolean false If `true`, the component-library-analytics event is disabled.

label label string The aria-label for the button group, used for accessibility. Not required, but recommended.

selected selected number 0 The index of the selected button.

Events

Name Description

component-library-analytics The event used to track usage of the component.

vaButtonClick Event emitted when selected button changes (a button is clicked).

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.
Consider 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, e.g., 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

While this component has been previously tested against older criteria, it has not yet been audited with the updated testing criteria.

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.

Edit this page in GitHub (Permissions required)

Last updated: Jun 27, 2025