Skip to content
On this page


A group of toggle buttons for 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).


Single value

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

Selected value: (null)

Reading direction

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

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)


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



Prop nameDescriptionTypeDefault
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 )[]
disabledWhether 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.


Event namePropertiesDescription
update:modelValuemodelValue string|number|( string|number )[] - The new model valueEmitted when modelValue changes.


defaultContent of an individual buttonbutton ButtonGroupItem - Object describing the button to display
selected boolean - Whether the button is selected