Segmented control

Examples

<script>
export default {
  data() {
    return {
      selected: 'tacos',
      options: [
        { value: 'pizza', text: 'Pizza' },
        { value: 'tacos', text: 'Tacos' },
        { value: 'burger', text: 'Burger', disabled: true },
      ],
    };
  },
};
</script>

<template>
  <gl-segmented-control :options="options" v-model="selected" aria-label="Meal choices" />
</template>

Structure

Guidelines

When to use

• If there are only a few options and enough room to fit within the UI.

When not to use

• When there are more than 5 options, use a select or dropdown instead to avoid overcrowding the UI.
• When options are not mutually exclusive and multiple selections are allowed, use checkboxes instead.
• When the selection triggers navigation to a different page or URL, use tabs instead.
• When the options represent on/off states for a single setting, use a toggle instead.
• When there is only one option, a segmented control is unnecessary.

Appearance

Buttons (Options)

• Each button must be equal in width and prominence.
• Button labels should ideally be only one word.

Labels

• Label positioning rules are the same as they are for forms. They can be placed to the left of segmented control when there’s a lack of vertical space. But by default, the label comes above the segmented control.
• The label can be omitted in cases when it’s clear what the segmented control is referring to from the UI (for example, switching between a day, week or month view in a calendar UI).
• Alternatively, icons can be used to replace button labels.

Behavior

• Results are effective and visible immediately.

Content

• Contain 2 or 3 options and should not go beyond 5.

Accessibility

• The segmented control renders as a group of buttons, which provides the correct semantics for a single-selection control. Screen readers announce the group label and each option's pressed state.
• Ensure the segmented control has an associated visible or accessible label so users understand what the options control.
  • Visible labels must be associated with the button group using aria-labelledby and a unique ID string.
  • aria-label can be used instead to create an accessible (non-visible) label.
• Keyboard navigation follows standard button behavior: press Tab to move focus forward and Shift + Tab to move focus backward.
• Keep disabled options visible so users know what choices exist, even when those options are not currently available.

Code reference

GlSegmentedControl

A customizable button group that displays a set of equal options, where only one option can be active at a time. This component includes the ability to disable specific options and dynamically modify button content using slots.

Features

• Displays a group of selectable buttons.
• Allows only one active selection at a time.
• Supports content customization through the button-content slot.
• Options can be disabled individually.

Props Validation

The options prop is validated against a specific structure to ensure consistent data. Each option must include:

• value: A string, number, or boolean to identify the option.
• disabled: A boolean (or undefined) indicating whether the option is disabled.

Optionally it can include:

• text: A string which gets displayed in the slot content.

Notes

• Ensure each value is unique within the options array for consistent behavior.

import { GlSegmentedControl } from '@gitlab/ui';