toggle button

Toggle buttons are a set of two or more options, each of which functions as a button. Use them to switch between alternative views of similar or related content in a contextual setting. For instance, the component allows users to toggle between a grid or list view, or to toggle between centimeters or inches.

Choosing the right component

Switches, checkboxes, radio buttons and toggle buttons are all similar types of selection controls, but are generally not interchangeable. If you're not sure which one to use for a certain scenario, use this comparison table.

The toggle button contains at least two selections, with a default option selected. You can also extend the component to include more than two. Take care in using toggle buttons that include more than five selections, as space on mobile is limited. Consider checking whether the toggle button will work on Cedar’s XS breakpoint.

Do

Do limit the number of segments to aid in usability and scanning.

Don't

Don't include more segments than what fit on the smallest breakpoint.

• Use nouns or noun phrases for labels
• As much as possible, use content with a similar character count in each segment

Use text-only labels when:

• Text/copy adequately informs the user of the expected content
• There is no CdrIcon to properly inform the user of represented content

Do

Do use content types that make sense for each experience.

Don't

Don't mix content types in the same toggle button.

What Cedar provides

• Sets the role of the unordered list to radiogroup
• Sets the role of the individual toggle buttons to radio
• Provides an aria-checked property for each toggle button

Development responsibilities

When using this component, here's what you are responsible for:

Always provide a toggleValue prop. The value of this property will be used as an aria-label attribute. This has the following uses:

• Spelling out abbreviated values (like "centimeters" instead of "cm") for screen readers
• Providing a label when only an icon is slotted to the toggle button

The parent CdrToggleGroup contains all the child CdrToggleButton components. This component will track the value of the selected toggle button among all the toggle buttons slotted to it. CdrToggleGroup requires v-model to track the value of the selected child CdrToggleButton.

<template>
   <cdr-toggle-group v-model="units">
      <cdr-toggle-button toggleValue="centimeters">cm</cdr-toggle-button>
      <cdr-toggle-button toggleValue="inches">in</cdr-toggle-button>
    </cdr-toggle-group>
</template>

The toggleValue prop of the selected CdrToggleButton will determine the modelValue of the selected toggle button. If no text or icon is slotted to the toggle button, the string provided for the required toggleValue prop displays as the button text. In cases where the slotted text and the toggleValue are different, as shown in the previous example, the slotted text gets displayed in the browser.

The modelValue of the CdrToggleGroup is always determined by the toggleValue prop of the selected CdrToggleButton. Also, screen readers will choose to read the toggleValue over the slotted text, which is handy in the case of abbreviations.