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

npm i @m3e/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 -->

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.

This 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/split-button/dist/index.js"></script>

You also need a module script for @m3e/button, @m3e/icon-button, @m3e/button-group, and @m3e/menu due to being dependencies.

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

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

<script type="importmap">
  {
    "imports": {
      "lit": "https://cdn.jsdelivr.net/npm/lit@3.3.0/+esm",
      "@m3e/core": "/node_modules/@m3e/core/dist/index.js",
      "@m3e/core/a11y": "/node_modules/@m3e/core/dist/a11y.js",
      "@m3e/core/anchoring": "/node_modules/@m3e/core/dist/anchoring.js",
      "@m3e/button": "/node_modules/@m3e/button/dist/index.js",
      "@m3e/icon-button": "/node_modules/@m3e/icon-button/dist/index.js"
    }
  }
</script>

For production, use index.min.js, a11y.min.js, and anchoring.min.js for faster load times.

This 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.