The m3e-split-button component presents a primary action alongside a menu of related actions, uniting two buttons in a single expressive surface.

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

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

The m3e-split-button exposes two action slots: leading-button for the primary intent, and trailing-button for invoking a menu of secondary options. The leading button executes the main action directly, while the trailing button reveals contextual alternatives via an attached menu.

The following example illustrates use of the m3e-button for the leading button, m3e-icon-button for the trailing button, and m3e-menu for presenting a menu of secondary options.

<m3e-split-button>
  <m3e-button slot="leading-button">
    <m3e-icon slot="icon" name="edit"></m3e-icon>Edit
  </m3e-button>
  <m3e-icon-button slot="trailing-button">
    <m3e-icon name="keyboard_arrow_down"></m3e-icon>
    <m3e-menu-trigger for="menu"></m3e-menu-trigger>
  </m3e-icon-button>
</m3e-split-button>
<m3e-menu id="menu" position-x="before">
  <m3e-menu-item>Rename</m3e-menu-item>
  <m3e-menu-item>Copy</m3e-menu-item>
  <m3e-menu-item>Delete</m3e-menu-item>
</m3e-menu>

There are four split button appearance variants: filled (default), tonal, outlined, and elevated. Use the variant attribute to change the appearance.

<m3e-split-button variant="filled">
  <m3e-button slot="leading-button">
    <m3e-icon slot="icon" name="edit"></m3e-icon>Edit
  </m3e-button>
  <m3e-icon-button slot="trailing-button">
    <m3e-icon name="keyboard_arrow_down"></m3e-icon>
    <m3e-menu-trigger for="menu"></m3e-menu-trigger>
  </m3e-icon-button>
</m3e-split-button>
<!-- Additional variants omitted for brevity -->
<!-- Menu omitted for brevity -->

There are five size variants which can be used to add or remove emphasis: extra-small, small (default), medium, large, and extra-large. Use the size attribute to control the split button's size.

<m3e-split-button size="extra-small">
  <m3e-button slot="leading-button">
    <m3e-icon slot="icon" name="edit"></m3e-icon>Edit
  </m3e-button>
  <m3e-icon-button slot="trailing-button">
    <m3e-icon name="keyboard_arrow_down"></m3e-icon>
    <m3e-menu-trigger for="menu"></m3e-menu-trigger>
  </m3e-icon-button>
</m3e-split-button>
<!-- Additional sizes omitted for brevity -->
<!-- Menu omitted for brevity -->

Split buttons 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 and menus 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 -3 density to the buttons and menu of a split button.

<m3e-split-button size="extra-small" class="density-3">
  <m3e-button slot="leading-button">
    <m3e-icon slot="icon" name="edit"></m3e-icon>Edit
  </m3e-button>
  <m3e-icon-button slot="trailing-button">
    <m3e-icon name="keyboard_arrow_down"></m3e-icon>
    <m3e-menu-trigger for="menu"></m3e-menu-trigger>
  </m3e-icon-button>
</m3e-split-button>

<m3e-menu id="menu" position-x="before" class="density-3">
  <!-- Menu items omitted for brevity -->
</m3e-menu>

.density-3 {
  --md-sys-density-scale: -3;
}

By default, split buttons are given the ARIA role group, indicating a set of related user interface elements that are grouped together.

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

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/split-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",
      "@m3e/web/core/a11y": "/node_modules/@m3e/web/dist/core-a11y.js",
      "@m3e/web/core/anchoring": "/node_modules/@m3e/web/dist/core-anchoring.js",
      "@m3e/web/button": "/node_modules/@m3e/web/button.js",
      "@m3e/web/icon-button": "/node_modules/@m3e/web/icon-button.js",
      "@m3e/web/button-group": "/node_modules/@m3e/web/button-group.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.