Skip to content


A button group consists of a set of two or more normal buttons. Buttons in such a group signal a number of equally important actions that will occur when the user taps on them.


When to use button groups

Each button within the button group must have a label. For icon-only buttons, the label will be visually hidden and available only to users of assistive technology.

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


Specification of ButtonGroup.

A button group consists of a minimum of two normal (framed) buttons, which may include the following elements:

  1. Icon (optional)
    Icons simplify user recognition and provide the ability to shorten button labels to a minimum.
  2. Label
    Button labels should be as short as possible, with text that clearly states what action will be taken once the button is pressed (e.g. download, submit form, search).

Component limitations

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

Maximum example for ButtonGroup component.

Refer to the ButtonGroup component in Codex Figma.

Interaction states

Button groups have the following visually separate states:

Interaction states of ButtonGroup: default,
hover on second button, second button active, focus on second button, disabled second button,
and disabled button group.

  1. Default buttons
  2. Hover on one button
  3. Active button
  4. Focus on one button
  5. Disabled button
  6. Disabled button group

Best practices

Consider the following recommendations when working with button groups.

Buttons within the group

ButtonGroup with two neutral normal text buttons.

  • Only neutral normal Buttons can be used within the ButtonGroup component.

Two ButtonGroups using progressive and destructive normal and primary buttons.

  • Use other flavors or weights of a Button within the ButtonGroup component.

Button’s content

Two ButtonGroups with text and text numeral neutral buttons.

  • Customize the content of each button, allowing for superscript, subscript, or special characters.
  • Use numbers instead of text if needed.
  • Mix text-only and icon-only buttons exclusively when using the ‘ellipsis‘ icon to indicate additional actions.

ButtonGroup with neutral buttons with mixed contents.

  • In order to ensure consistency, avoid mixing different types of button contents within the same ButtonGroup.

Icon-only buttons

ButtonGroup using icon-only buttons with universally recognizable icons.

  • Icon-only buttons may be used to form a ButtonGroup but only if the icons used are universally understood and do not require accompanying text.

ButtonGroup using icon-only buttons with too complex and non-universal icons.

  • Use icon-only buttons if the icons are not easy to understand or do not clearly communicate their purpose.

Keyboard navigation

TabIt 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 + TabIt 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 / SpaceIf the focus is placed on one of the buttons, it activates that Button.


Open up the browser console to see events emitted on click.

Basic usage

Describe the buttons in the group with an array of ButtonGroupItem objects. The text in the label property will be displayed in the buttons. When a button is clicked, a click event will be emitted with the value property of the clicked button. Values must be unique within a button group.

If the label property is omitted, the value property will be used as the label. This allows using { value: 'Foo' } as a shorthand for { label: 'Foo', value: 'Foo' }.

Reading direction

With icons

Use the icon property to add an icon before the text of a button. Use the disabled property to disable individual buttons.

Icon-only buttons

To display an icon as the only content of a button, use the icon property to specify an icon, and set the label property to null.


The entire component can be disabled by setting the disabled prop. Individual buttons can be disabled by setting their .disabled property. Clicking a disabled button does not emit a click event.

Overflowing buttons

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

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. In this example, the value of the button is displayed in superscript after its label.

Vue usage


Prop nameDescriptionTypeDefault
buttons(required)Objects describing the buttons in the group. See the ButtonGroupItem type.ButtonGroupItem[]
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
clickvalue string|number - The value property of the button that was clickedEmitted when a button is clicked


defaultContent of an individual buttonbutton ButtonGroupItem - Object describing the button to display