ToggleButtonGroup

A ToggleButtonGroup is a group of ToggleButtons that allows users to select one or multiple buttons from the group.

Guidelines

Using toggle button groups

Buttons within the toggle button group must carry a label. In the case of icon-only buttons, the label will be available only to screen reader users.

Use the ToggleButtonGroup when you require users to select either one or multiple options from a group. If you want users to choose from a set of actions, with the restriction that only one can be active simultaneously, use the ButtonGroup instead.

Specifications

A toggle button group consists of of a minimum of 2 toggle buttons, which may include the following elements:

Icon (optional)
Icons simplify user recognition and provide the ability to shorten button labels to a minimum.
Label
Button labels should be as short as possible, with text that clearly states what option will be selected when the button is toggled on.
White line
For toggled-on buttons, a white line is added to visually separate them, whether they are on the same line or placed on different rows in the stacked version.

There is no maximum limit on the number of toggle buttons per group. The width of the ToggleButtonGroup will adjust to accommodate the expanding text within each button. If the total width surpasses the maximum width of max-width-button token (equivalent to 448px in the default Codex theme), the buttons will be arranged into the next row.

Refer to the ToggleButtonGroup component in Codex Figma.

Interaction states

ToggleButtonGroups have the following visually separate states:

Default
Hover on one button
Active button
Focus on one button
One button is selected
One button is disabled
Hover on the selected button
The selected button is active
Focus on the selected button
Two buttons are selected
All buttons are selected
All buttons are disabled

Best practices

Consider the following recommendations when working with toggle button groups.

Button’s content

Do:

Consider using text-only, text with icon, or icon-only buttons within the ToggleButtonGroup.
Use numbers instead of text within the buttons if appropriate.

Don't:

Mix different types of buttons within the same ToggleButtonGroup to maintain consistency.

Icon-only buttons

Do:

Use icon-only toggle buttons to create a ToggleButtonGroup if needed.
Ensure the icons used are universally recognizable and don't need accompanying text.

Don't:

Use icon-only buttons if the icons are unclear or don't effectively convey their purpose.

Key	Function
`Tab`	It moves the focus to the next button within the group or to the next interactive element in tab order when the focus is placed on the last button of the group.
`Shift` + `Tab`	It moves the focus to the previous button within the group or to the previous interactive element when the focus is placed on the first button of the group.
`Enter` / `Space`	If the focus is placed on one of the toggle buttons within the group, it toggles that button on and off.

Demos

Single value

To allow only a single value to be selected, initialize v-model to null.

Selected value: (null)

Name	Value
View
Reading direction	Left to right (LTR) Right to left (RTL)

Initially selected single value

To start with one button already selected, initialize v-model to that value.

Use the icon property to add an icon before the text of a button. Use the disabled property to disable individual buttons. For more information on how to control the appearance of each button, see the ButtonGroup documentation.

Selected value: framed

NPMMediaWiki

vue

<template>
	<cdx-toggle-button-group
		v-model="selectedValue"
		:buttons="buttons"
	/>
	<p>
		Selected value:
		{{ selectedValue || '(null)' }}
	</p>
</template>

<script>
import { defineComponent, ref } from 'vue';
import { CdxToggleButtonGroup } from '@wikimedia/codex';
import {
	cdxIconImageLayoutBasic,
	cdxIconImageLayoutFrame,
	cdxIconImageLayoutFrameless,
	cdxIconImageLayoutThumbnail
} from '@wikimedia/codex-icons';

export default defineComponent( {
	name: 'InitiallySelectedSingleValueToggleButtonGroup',
	components: {
		CdxToggleButtonGroup
	},
	setup() {
		const buttons = [
			{ value: 'basic', label: 'Basic', icon: cdxIconImageLayoutBasic },
			{ value: 'framed', label: 'Framed', icon: cdxIconImageLayoutFrame },
			{ value: 'frameless', label: 'Frameless', icon: cdxIconImageLayoutFrameless },
			{ value: 'thumbnail', label: 'Thumbnail', icon: cdxIconImageLayoutThumbnail, disabled: true }
		];

		// Initially select the 'Framed' button
		const selectedValue = ref( 'framed' );

		return {
			buttons,
			selectedValue
		};
	}
} );
</script>

vue

<template>
	<cdx-toggle-button-group
		v-model="selectedValue"
		:buttons="buttons"
	></cdx-toggle-button-group>
	<p>
		Selected value:
		{{ selectedValue || '(null)' }}
	</p>
</template>

<script>
const { defineComponent, ref } = require( 'vue' );
const { CdxToggleButtonGroup } = require( '@wikimedia/codex' );
const {
	cdxIconImageLayoutBasic,
	cdxIconImageLayoutFrame,
	cdxIconImageLayoutFrameless,
	cdxIconImageLayoutThumbnail
} = require( './icons.json' );

// @vue/component
module.exports = defineComponent( {
	name: 'InitiallySelectedSingleValueToggleButtonGroup',
	components: {
		CdxToggleButtonGroup
	},
	setup() {
		const buttons = [
			{ value: 'basic', label: 'Basic', icon: cdxIconImageLayoutBasic },
			{ value: 'framed', label: 'Framed', icon: cdxIconImageLayoutFrame },
			{ value: 'frameless', label: 'Frameless', icon: cdxIconImageLayoutFrameless },
			{ value: 'thumbnail', label: 'Thumbnail', icon: cdxIconImageLayoutThumbnail, disabled: true }
		];

		// Initially select the 'Framed' button
		const selectedValue = ref( 'framed' );

		return {
			buttons,
			selectedValue
		};
	}
} );
</script>

Multiple values

To allow multiple values to be selected, initialize v-model to an empty array ([]). To start with some of buttons already selected, initialize v-model to an array of the values of those buttons.

Selected values: (none)

Disabled

The entire component can be disabled by setting the disabled prop. Individual buttons can be disabled by setting their .disabled property.

Overflowing buttons

When the button group is too large to fit on one line, the buttons overflow to the next line.

Selected values: (none)

Custom button display

The contents of the buttons can be customized using the default slot. The ButtonGroupItem object for each button is available through the button binding, and the selected state of each button is available through the selected binding. In this example, the value of the button is displayed after its label, but only if the button is selected.

Selected value: 2

Vue usage

Whether the group is single-select or multi-select is automatically detected based on the value bound to v-model: if it's an array, the group allows multiple selections; otherwise, it only allows a single selection. To initially select nothing, initialize the v-model value to null (for single-select groups) or [] (for multi-select groups).

Props

Prop name	Description	Type	Default
`buttons`^(required)	Buttons to display. See the ButtonGroupItem type.	`ButtonGroupItem[]`
`modelValue`^(required)	Selected value, or array of selected values. If this is a string or number, the button whose value equals that string or number is selected, and only a single selection is allowed. If this is an array, the buttons whose values equal any of the values in the array are selected, and multiple selections are allowed. To select none of the buttons initially, set this to `null` (for single-selection groups) or to `[]` (for multi-selection groups). Must be bound with `v-model`.	`string\|number\|null\|( string\|number )[]`
`disabled`	Whether the entire group is disabled. If this is set to true, all buttons in the group are disabled. Buttons can also be disabled individually by setting their `disabled` property to true.	`boolean`	`false`

Events

Event name	Properties	Description
`update:modelValue`	modelValue `string\|number\|( string\|number )[]` - The new model value	Emitted when modelValue changes.

Slots

Name	Description	Bindings
default	Content of an individual button	button `ButtonGroupItem` - Object describing the button to display selected `boolean` - Whether the button is selected

ToggleButtonGroup ​

Guidelines ​

Using toggle button groups ​

Specifications ​

Interaction states ​

Best practices ​

Button’s content ​

Icon-only buttons ​

Keyboard navigation ​

Demos ​

Single value ​

Initially selected single value ​

Multiple values ​

Disabled ​

Overflowing buttons ​

Custom button display ​

Vue usage ​

Props ​

Events ​

Slots ​