The m3e-button-group component arranges multiple into a unified, expressive layout.

import "@m3e/web/button-group";

This section outlines usage examples and configuration guidance for the components in this package.

There are two appearance variants: standard (default) and connected. Use the variant attribute to change the appearance.

Standard button groups add interaction between adjacent buttons

<m3e-button-group>
  <m3e-icon-button>
    <m3e-icon name="arrow_back"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button>
    <m3e-icon name="arrow_forward"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button width="wide" variant="filled">
    <m3e-icon name="add"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button>
    <m3e-icon name="picture_in_picture"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button>
    <m3e-icon name="more_vert"></m3e-icon>
  </m3e-icon-button>
</m3e-button-group>

Standard button groups can contain textual buttons.

<m3e-button-group>
  <m3e-button variant="tonal">
    <m3e-icon slot="icon" name="play_arrow"></m3e-icon>Start
  </m3e-button>
  <m3e-button variant="tonal">
    <m3e-icon slot="icon" name="directions_car"></m3e-icon>Directions
  </m3e-button>
  <m3e-button variant="tonal">
    <m3e-icon slot="icon" name="share"></m3e-icon>Share
  </m3e-button>
</m3e-button-group>

Standard button groups can contain mixed button types and supports narrow and wide icon button widths.

<m3e-button-group>
  <m3e-icon-button variant="filled" width="wide">
    <m3e-icon name="fast_rewind"></m3e-icon>
  </m3e-icon-button>
  <m3e-button variant="filled">
    <m3e-icon slot="icon" name="play_arrow"></m3e-icon>Play
  </m3e-button>
  <m3e-icon-button variant="filled" width="wide">
    <m3e-icon name="fast_forward"></m3e-icon>
  </m3e-icon-button>
</m3e-button-group>

Connected button groups behave similarly to standard groups, except they don't affect adjacent buttons and fill available space.

<m3e-button-group variant="connected">
  <m3e-button variant="tonal" toggle>Start</m3e-button>
  <m3e-button variant="tonal" toggle>Directions</m3e-button>
  <m3e-button variant="tonal" toggle>Share</m3e-button>
</m3e-button-group>

Icon buttons will also grow to fill available space.

There are five size variants used to control spacing between button: extra-small, small (default), medium, large, and extra-large. Use the size attribute control spacing. To create buttons with a uniform size, set each button's size to the same size as the button group.

<m3e-button-group size="large">
  <m3e-icon-button size="large">
    <m3e-icon name="arrow_back"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button size="large">
    <m3e-icon name="arrow_forward"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button size="large" width="wide" variant="filled">
    <m3e-icon name="add"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button size="large">
    <m3e-icon name="picture_in_picture"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button size="large">
    <m3e-icon name="more_vert"></m3e-icon>
  </m3e-icon-button>
</m3e-button-group>

Connected button groups always have the same spacing between buttons, regardless of size.

<m3e-button-group size="large" variant="connected">
  <m3e-button variant="tonal" size="large" toggle>Start</m3e-button>
  <m3e-button variant="tonal" size="large" toggle>Directions</m3e-button>
  <m3e-button variant="tonal" size="large" toggle>Share</m3e-button>
</m3e-button-group>

Button groups containing toggle buttons support both single-select and multi-select modes. Use the multi attribute to allow multiple toggle buttons to be selected simultaneously.

<m3e-button-group multi>
  <m3e-icon-button variant="tonal" toggle>
    <m3e-icon name="format_bold"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button variant="tonal" toggle>
    <m3e-icon name="format_italic"></m3e-icon>
  </m3e-icon-button>
  <m3e-icon-button variant="tonal" toggle>
    <m3e-icon name="format_underlined"></m3e-icon>
  </m3e-icon-button>
</m3e-button-group>

Buttons and icon buttons in a group are density-aware and adjust their vertical spacing based on the --md-sys-density-scale and --md-sys-density-size custom CSS properties. The default density size is 4dp (0.25rem). Buttons support negative density scales down to -3, with each step reducing the visual height by one density unit. Regardless of visual size, buttons maintain a 48x48dp minimum touch target to ensure reliable accessibility.

The following illustrates applying density to both the standard and connected variants.

<m3e-button-group class="density-3">
  <!-- Buttons omitted for brevity -->
</m3e-button-group>
<!-- Additional groups and variants omitted for brevity -->

.density-3 {
  --md-sys-density-scale: -3;
}
/* Additional classes omitted for brevity */

By default, button groups are given the ARIA role group, indicating a set of related user interface elements that are grouped together. For a single-select group containing one or more toggle buttons, button groups are given the ARIA role radiogroup and buttons are given the role radio.

Always provide an accessible label via aria-label or aria-labelledby for each button group.

The @m3e/web package uses JavaScript Modules. To use it directly in a browser without a bundler, use a module script similar to the following.

<script type="module" src="/node_modules/@m3e/web/dist/button-group.js"></script>

You also need a module script for @m3e/button and @m3e/icon-button due to being a dependency.

<script type="module" src="/node_modules/@m3e/web/dist/button.js"></script>
<script type="module" src="/node_modules/@m3e/web/dist/icon-button.js"></script>

In addition, you must use an import map to include additional dependencies.

<script type="importmap">
  {
    "imports": {
      "tslib": "https://cdn.jsdelivr.net/npm/tslib@2.8.1/+esm",
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "lit/": "https://cdn.jsdelivr.net/npm/lit@3.3.0/",
      "lit-html": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/+esm",
      "lit-html/directive.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directive.js",
      "lit-html/directives/if-defined.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/if-defined.js",
      "lit-html/directives/class-map.js": "https://cdn.jsdelivr.net/npm/lit-html@3.3.0/directives/class-map.js",
      "@lit/reactive-element": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/+esm",
      "@lit/reactive-element/": "https://cdn.jsdelivr.net/npm/@lit/reactive-element@2.0.4/",
      "@m3e/web/core": "/node_modules/@m3e/web/dist/core.js"
    }
  }
</script>

For production builds, use the minified files to ensure optimal load performance.

The @m3e/web package includes a Custom Elements Manifest (custom-elements.json), which documents the properties, attributes, slots, events and CSS custom properties of each component.

You can explore the API below, or integrate the manifest into your own tooling.