Codex Direction:
ToggleButtonGroup #
Group of toggle buttons that allows making a selection.
Single-select groups behave like a group of radio buttons: only one value can be selected, and clicking an already-selected value has no effect. Multi-select groups behave like a group of checkboxes: multiple values can be selected, and clicking an already-selected value unselects it.
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).
Demos #
Single value #
To allow only a single value to be selected, initialize v-model to null.
Selected value: (null)
vue
<template>
<cdx-toggle-button-group
v-model="selectedValue"
:buttons="buttons"
/>
<p>
Selected value:
{{ selectedValue ?? '(null)' }}
</p>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxToggleButtonGroup, ButtonGroupItem } from '@wikimedia/codex';
export default defineComponent( {
name: 'SingleValueToggleButtonGroup',
components: {
CdxToggleButtonGroup
},
setup() {
const buttons: ButtonGroupItem[] = [
{ value: 1, label: 'One' },
{ value: 2, label: 'Two' },
{ value: 3, label: 'Three' },
{ value: 4, label: 'Four' },
{ value: 5, label: 'Five' }
];
// Initializing to null indicates that this is a single-select group
const selectedValue = ref<number|null>( null );
return {
buttons,
selectedValue
};
}
} );
</script>
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
vue
<template>
<cdx-toggle-button-group
v-model="selectedValue"
:buttons="buttons"
/>
<p>
Selected value:
{{ selectedValue ?? '(null)' }}
</p>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxToggleButtonGroup, ButtonGroupItem } from '@wikimedia/codex';
import {
cdxIconImageLayoutBasic,
cdxIconImageLayoutFrame,
cdxIconImageLayoutFrameless,
cdxIconImageLayoutThumbnail
} from '@wikimedia/codex-icons';
export default defineComponent( {
name: 'InitiallySelectedSingleValueToggleButtonGroup',
components: {
CdxToggleButtonGroup
},
setup() {
const buttons: ButtonGroupItem[] = [
{ 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)
vue
<template>
<cdx-toggle-button-group
v-model="selectedValue"
:buttons="buttons"
/>
<p>
Selected values:
{{ selectedValue.join( ', ' ) || '(none)' }}
</p>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxToggleButtonGroup, ButtonGroupItem } from '@wikimedia/codex';
import { cdxIconBell, cdxIconCalendar, cdxIconUserAvatar } from '@wikimedia/codex-icons';
export default defineComponent( {
name: 'MultiValueToggleButtonGroup',
components: {
CdxToggleButtonGroup
},
setup() {
const buttons: ButtonGroupItem[] = [
{ value: 'notification', label: null, icon: cdxIconBell, ariaLabel: 'Notification' },
{ value: 'calendar', label: null, icon: cdxIconCalendar, ariaLabel: 'Calendar' },
{ value: 'user', label: null, icon: cdxIconUserAvatar, ariaLabel: 'User' }
];
// Initializing to an array indicates that this is a multi-select group
const selectedValue = ref<string[]>( [] );
return {
buttons,
selectedValue
};
}
} );
</script>
Disabled #
The entire component can be disabled by setting the disabled prop. Individual buttons can be disabled by setting their .disabled property.
vue
<template>
<cdx-toggle-button-group
v-model="selectedValue"
:buttons="buttons"
:disabled="true"
/>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxToggleButtonGroup, ButtonGroupItem } from '@wikimedia/codex';
export default defineComponent( {
name: 'SingleValueToggleButtonGroup',
components: {
CdxToggleButtonGroup
},
setup() {
const buttons: ButtonGroupItem[] = [
{ value: 1, label: 'One' },
{ value: 2, label: 'Two' },
{ value: 3, label: 'Three' },
{ value: 4, label: 'Four', disabled: true },
{ value: 5, label: 'Five' }
];
const selectedValue = ref<string|number|null>( null );
return {
buttons,
selectedValue
};
}
} );
</script>
Overflowing buttons #
When the button group is too large to fit on one line, the buttons overflow to the next line.
Selected values: (none)
vue
<template>
<cdx-toggle-button-group
v-model="selectedValue"
:buttons="buttons"
/>
<p>
Selected values:
{{ selectedValue.join( ', ' ) || '(none)' }}
</p>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxToggleButtonGroup, ButtonGroupItem } from '@wikimedia/codex';
export default defineComponent( {
name: 'MaximumToggleButtonGroup',
components: {
CdxToggleButtonGroup
},
setup() {
const buttons: ButtonGroupItem[] = [
{ value: 1, label: 'First button' },
{ value: 2, label: 'Second button' },
{ value: 3, label: 'Third button with a long label' },
{ value: 4, label: 'Fourth button with a long label' },
{ value: 5, label: 'Fifth button' }
];
const selectedValue = ref<number[]>( [] );
return {
buttons,
selectedValue
};
}
} );
</script>
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
<template>
<cdx-toggle-button-group
v-model="selectedValue"
:buttons="buttons"
>
<template #default="{ button, selected }">
{{ button.label }}
<span v-if="selected">
({{ button.value }})
</span>
</template>
</cdx-toggle-button-group>
<p>
Selected value:
{{ selectedValue ?? '(null)' }}
</p>
</template>
<script lang="ts">
import { defineComponent, ref } from 'vue';
import { CdxToggleButtonGroup, ButtonGroupItem } from '@wikimedia/codex';
export default defineComponent( {
name: 'ToggleButtonGroupWithSlot',
components: {
CdxToggleButtonGroup
},
setup() {
const buttons: ButtonGroupItem[] = [
{ value: 1, label: 'One' },
{ value: 2, label: 'Two' }
];
const selectedValue = ref( 2 );
return {
buttons,
selectedValue
};
}
} );
</script>
Usage #
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 displayselected boolean - Whether the button is selected |