The m3e-segmented-button component allows users to select one or more options from a horizontal group.

npm i @m3e/segmented-button

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

A segmented button is defined using the m3e-segmented-button component, which serves as a semantic container for a set of interactive segments. Each segment is represented by a m3e-button-segment component, allowing users to select from multiple related options within a unified control.

<m3e-segmented-button>
  <m3e-button-segment checked>8 oz</m3e-button-segment>
  <!-- Additional segments omitted for brevity -->
</m3e-segmented-button>

Use the icon slot of the m3e-button-segment to present an icon before a segment's label.

When selected, a segments's icon is replaced with a check icon.

<m3e-segmented-button>
  <m3e-button-segment>
    <m3e-icon slot="icon" name="palette"></m3e-icon>Design
  </m3e-button-segment>
  <!-- Additional segments omitted for brevity -->
</m3e-segmented-button>

Segmented buttons support both single-select and multi-select modes. Use the multi attribute of m3e-segmented-button to allow multiple segments to be selected simultaneously.

Use the checked attribute to control the selected state of a m3e-button-segment. When clicked, a cancellable input event is emitted followed by a change event. To cancel selection change, call preventDefault during input.

<m3e-segmented-button multi>
  <m3e-button-segment checked>8 oz</m3e-button-segment>
  <m3e-button-segment checked>12 oz</m3e-button-segment>
  <!-- Additional segments omitted for brevity -->
</m3e-segmented-button>

Use the disabled attribute to disable an individual segment.

<m3e-segmented-button>
  <m3e-button-segment disabled>
    <m3e-icon slot="icon" name="palette"></m3e-icon>Design
  </m3e-button-segment>
  <!-- Additional segments omitted for brevity -->
</m3e-segmented-button>

You can also use the disabled attribute of m3e-segmented-button to disable the button in its entirety.

<m3e-segmented-button disabled>
  <m3e-button-segment>
    <m3e-icon slot="icon" name="palette"></m3e-icon>Design
  </m3e-button-segment>
  <!-- Additional segments omitted for brevity -->
</m3e-segmented-button>

Use the hide-selection-indicator attribute of m3e-segmented-button to hide selection indicators. If a segment has an icon via use of the icon slot, the icon is retained upon selection.

<m3e-segmented-button hide-selection-indicator>
  <!-- Segments omitted for brevity -->
</m3e-segmented-button>

Segmented buttons can participate in form submission as a form-associated custom element (FACE), contributing its state to the form data. The name attribute defines the key under which the component's value is submitted in a form. The button's value is determined by selected segments. You can use the value of a m3e-button-segment to control a segments's value. When multiple segments are selected, form data will include multiple entries keyed by the same name.

The component honors the disabled state (on the segmented button itself) as a property-only control. When disabled at runtime, it does not sprout a disabled attribute into the DOM.

Segmented buttons are given the ARIA role="radiogroup" and segments are given role="radio" for single-select buttons. For multi-select, buttons are given role="group" and segments are given role="button". When selected, the segments's selection state is reflected using aria-checked for single-select buttons and aria-pressed for multi-select buttons.

For disabled single-select segmented buttons, aria-disabled is not applied to the button. Instead, the disabled state is reflected by applying aria-disabled="true" to each nested segment, ensuring assistive technologies correctly interpret the non-interactive status of individual options. For disabled multi-select segmented buttons, aria-disabled is applied to the button as well as individual segments. When a segmented button is disabled at runtime, it does not sprout a disabled attribute into the DOM.

Always provide an accessible label via aria-label or aria-labelledby for each segmented 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/segmented-button/dist/index.js"></script>

In addition, you must use an import map to include 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"
    }
  }
</script>

For production, use index.min.js and a11y.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.