Skip to main contentSkip to docs navigation
View on GitHub

Button group

Create cohesive sets of related actions through semantically grouped buttons that maintain your design system's visual language.

On this page
@layer components
Depends onButton
Context tokens

Introduction

Button groups in Chassis CSS organize related actions into a cohesive component that preserves your design token system's visual language. Unlike one-off button collections, button groups maintain consistent spacing, borders, and visual relationships that signal to users that the buttons belong together conceptually.

Basic implementation

Apply the .button-group class to a container element wrapping a series of .button elements. The button group component automatically handles borders and spacing between buttons.

HTML
<div class="button-group" role="group" aria-label="Basic example">
  <button type="button" class="button default">Left</button>
  <button type="button" class="button default">Middle</button>
  <button type="button" class="button default">Right</button>
</div>
<div class="button-group" role="group" aria-label="Basic example">
  <button type="button" class="button primary">Left</button>
  <button type="button" class="button primary">Middle</button>
  <button type="button" class="button primary">Right</button>
</div>

Accessibility: Button groups require proper ARIA attributes to ensure assistive technologies correctly identify and announce grouped buttons. Use role="group" for standard button groups or role="toolbar" for button toolbars, along with aria-label or aria-labelledby to provide a descriptive label for the group.

Button groups work equally well with anchor links that use the .button class, providing a unified experience across different interactive elements:

Active link Link Link
HTML
<div class="button-group">
  <a href="#" class="button primary active" aria-current="page">Active link</a>
  <a href="#" class="button primary">Link</a>
  <a href="#" class="button primary">Link</a>
</div>

Contextual variations

Button groups seamlessly integrate with Chassis's contextual color system, allowing you to apply your design system's semantic colors consistently across grouped controls.

HTML
<div class="button-group" role="group" aria-label="Contextual button group example">
  <button type="button" class="button danger">Left</button>
  <button type="button" class="button warning">Middle</button>
  <button type="button" class="button success">Right</button>
</div>

Visual variants

Chassis's button variants work harmoniously within button groups, maintaining their distinctive visual characteristics while preserving the group's cohesive structure.

Outline variant

Use the .outline modifier for a more subtle, border-focused appearance that maintains contextual meaning:

HTML
<div class="button-group" role="group" aria-label="Basic outline example">
  <button type="button" class="button outline primary">Left</button>
  <button type="button" class="button outline primary">Middle</button>
  <button type="button" class="button outline primary">Right</button>
</div>

Smooth variant

Apply the .smooth modifier for a softer, more subdued appearance with reduced visual weight:

HTML
<div class="button-group" role="group" aria-label="Basic smooth example">
  <button type="button" class="button smooth primary">Left</button>
  <button type="button" class="button smooth primary">Middle</button>
  <button type="button" class="button smooth primary">Right</button>
</div>

Form integration

Chassis enables seamless integration of form elements within button groups, creating toggle-style interfaces where users can make selections that visually align with your button design language.

Checkbox toggle buttons

Create multi-selection controls using checkbox inputs combined with button styling:

HTML
<div class="button-group" role="group" aria-label="Checkbox toggle button group">
  <label class="button button-check outline primary">
    <input type="checkbox" autocomplete="off">
    Checkbox 1
  </label>

  <label class="button button-check outline primary">
    <input type="checkbox" autocomplete="off">
    Checkbox 2
  </label>

  <label class="button button-check outline primary">
    <input type="checkbox" autocomplete="off">
    Checkbox 3
  </label>
</div>

Radio toggle buttons

Create single-selection controls that maintain visual consistency with your button design tokens:

HTML
<div class="button-group" role="group" aria-label="Radio toggle button group">
  <label class="button button-check outline primary">
    <input type="radio" name="buttonradio" autocomplete="off" checked>
    Radio 1
  </label>

  <label class="button button-check outline primary">
    <input type="radio" name="buttonradio" autocomplete="off">
    Radio 2
  </label>

  <label class="button button-check outline primary">
    <input type="radio" name="buttonradio" autocomplete="off">
    Radio 3
  </label>
</div>

Toggle buttons combine the visual consistency of the button component with the functional behavior of form controls, making them ideal for option selection within a cohesive interface.

Button toolbars

Button toolbars combine multiple button groups into a unified control interface, typically used for more complex interactions with multiple related functions.

Basic toolbar

Create a toolbar by wrapping multiple .button-group elements in a .button-toolbar container:

HTML
<div class="button-toolbar" role="toolbar" aria-label="Toolbar with button groups">
  <div class="button-group me-xsmall" role="group" aria-label="First group">
    <button type="button" class="button primary">1</button>
    <button type="button" class="button primary">2</button>
    <button type="button" class="button primary">3</button>
    <button type="button" class="button primary">4</button>
  </div>
  <div class="button-group me-xsmall" role="group" aria-label="Second group">
    <button type="button" class="button secondary">5</button>
    <button type="button" class="button secondary">6</button>
    <button type="button" class="button secondary">7</button>
  </div>
  <div class="button-group" role="group" aria-label="Third group">
    <button type="button" class="button info">8</button>
  </div>
</div>

Accessibility: When using button toolbars, apply role="toolbar" and provide an appropriate aria-label to ensure assistive technologies properly announce the toolbar's purpose.

Combined form controls

Button toolbars support integration with form controls, offering a comprehensive solution for complex UIs:

HTML
<div class="button-toolbar mb-medium" role="toolbar" aria-label="Toolbar with button groups and input">
  <div class="button-group me-xsmall" role="group" aria-label="Control group">
    <button type="button" class="button outline secondary">1</button>
    <button type="button" class="button outline secondary">2</button>
    <button type="button" class="button outline secondary">3</button>
    <button type="button" class="button outline secondary">4</button>
  </div>
  <div class="input-group">
    <div class="input-addon" id="buttonGroupAddon">@</div>
    <input type="text" class="form-input" placeholder="Input group example" aria-label="Input group example" aria-describedby="buttonGroupAddon">
  </div>
</div>

Use Chassis's layout utilities to control spacing and alignment within toolbars:

HTML
<div class="button-toolbar justify-content-between" role="toolbar" aria-label="Toolbar with spaced elements">
  <div class="button-group" role="group" aria-label="Button controls">
    <button type="button" class="button outline secondary">1</button>
    <button type="button" class="button outline secondary">2</button>
    <button type="button" class="button outline secondary">3</button>
    <button type="button" class="button outline secondary">4</button>
  </div>
  <div class="input-group">
    <div class="input-addon" id="buttonGroupAddon2">@</div>
    <input type="text" class="form-input" placeholder="Input group example" aria-label="Input group example" aria-describedby="buttonGroupAddon2">
  </div>
</div>

Size variants

Apply consistent sizing across all buttons in a group by adding the size modifier class (.large or .small) directly to the .button-group container rather than to individual buttons:



HTML
<div class="button-group large" role="group" aria-label="Large button group">
  <button type="button" class="button outline primary">Left</button>
  <button type="button" class="button outline primary">Middle</button>
  <button type="button" class="button outline primary">Right</button>
</div>
<br /><br />
<div class="button-group small" role="group" aria-label="Small button group">
  <button type="button" class="button outline primary">Left</button>
  <button type="button" class="button outline primary">Middle</button>
  <button type="button" class="button outline primary">Right</button>
</div>

When nesting button groups, apply size classes to each group container that needs sizing, including nested groups.

Nesting

Place a .button-group within another .button-group when you want dropdown menus mixed with a series of buttons.

HTML
<div class="button-group" role="group" aria-label="Button group with nested dropdown">
  <button type="button" class="button primary">1</button>
  <button type="button" class="button primary">2</button>
  <div class="button-group" role="group">
    <button type="button" class="button primary menu-toggle" data-cx-toggle="menu" aria-expanded="false">
      Dropdown
    </button>
    <ul class="menu">
      <li><a class="menu-item" href="#">Dropdown link</a></li>
      <li><a class="menu-item" href="#">Dropdown link</a></li>
    </ul>
  </div>
</div>

Vertical orientation

Transform button groups from horizontal to vertical orientation using the .button-group-vertical class:

HTML
<div class="button-group-vertical" role="group" aria-label="Vertical button group">
  <button type="button" class="button primary">Button</button>
  <button type="button" class="button primary">Button</button>
  <button type="button" class="button primary">Button</button>
  <button type="button" class="button primary">Button</button>
</div>

Vertical button groups support the same dropdown integration as horizontal groups:

HTML
<div class="button-group-vertical" role="group" aria-label="Vertical button group with dropdowns">
  <button type="button" class="button primary">Button</button>
  <button type="button" class="button primary">Button</button>
  <div class="button-group" role="group">
    <button type="button" class="button primary menu-toggle" data-cx-toggle="menu" aria-expanded="false">
      Dropdown
    </button>
    <ul class="menu">
      <li><a class="menu-item" href="#">Dropdown link</a></li>
      <li><a class="menu-item" href="#">Dropdown link</a></li>
    </ul>
  </div>
  <div class="button-group dropstart" role="group">
    <button type="button" class="button primary menu-toggle" data-cx-toggle="menu" aria-expanded="false">
      Dropdown
    </button>
    <ul class="menu">
      <li><a class="menu-item" href="#">Dropdown link</a></li>
      <li><a class="menu-item" href="#">Dropdown link</a></li>
    </ul>
  </div>
  <div class="button-group dropend" role="group">
    <button type="button" class="button primary menu-toggle" data-cx-toggle="menu" aria-expanded="false">
      Dropdown
    </button>
    <ul class="menu">
      <li><a class="menu-item" href="#">Dropdown link</a></li>
      <li><a class="menu-item" href="#">Dropdown link</a></li>
    </ul>
  </div>
  <div class="button-group dropup" role="group">
    <button type="button" class="button primary menu-toggle" data-cx-toggle="menu" aria-expanded="false">
      Dropdown
    </button>
    <ul class="menu">
      <li><a class="menu-item" href="#">Dropdown link</a></li>
      <li><a class="menu-item" href="#">Dropdown link</a></li>
    </ul>
  </div>
</div>

Vertical button groups also support the same form controls integration as horizontal groups:

HTML
<div class="button-group-vertical" role="group" aria-label="Vertical radio toggle button group">
  <label class="button button-check outline danger">
    <input type="radio" name="vbutton-radio" autocomplete="off" checked>
    Radio 1
  </label>
  <label class="button button-check outline danger">
    <input type="radio" name="vbutton-radio" autocomplete="off">
    Radio 2
  </label>
  <label class="button button-check outline danger">
    <input type="radio" name="vbutton-radio" autocomplete="off">
    Radio 3
  </label>
</div>