The @m3e/chips package provides expressive, accessible chip components for actions, input, filtering, and suggestions.

npm i @m3e/chips

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

Use the m3e-chip component to present a non-interactive chip. You can optionally nest chips in a m3e-chip-set which provides default spacing between chips.

<m3e-chip-set>
  <m3e-chip>Confidential</m3e-chip>
  <m3e-chip>Draft</m3e-chip>
  <m3e-chip>Finance</m3e-chip>
  <m3e-chip>Presentation</m3e-chip>
</m3e-chip-set>

All chip types support two appearance variants: outlined (default) and elevated. Use the variant attribute to change a chip's appearance.

<m3e-chip>Outlined</m3e-chip>
<m3e-chip variant="elevated">Elevated</m3e-chip>

Chips can be stacked vertically using the vertical attribute of a m3e-chip-set.

<m3e-chip-set vertical>
  <m3e-chip>Confidential</m3e-chip>
  <m3e-chip>Draft</m3e-chip>
  <m3e-chip>Finance</m3e-chip>
  <m3e-chip>Presentation</m3e-chip>
</m3e-chip-set>

The m3e-chip provides slots for two icons. Use the icon slot to present an icon before a chip's label and use the trailing-icon slot to present an icon after it. While not required, the following example uses the m3e-icon component from @m3e/icon to present icons using Material Symbols.

<m3e-chip>
  <m3e-icon slot="icon" name="finance"></m3e-icon>
  Finance
</m3e-chip>

Use the m3e-assist-chip to perform a smart or automated action that can span multiple applications.

<m3e-assist-chip>Outlined Assist</m3e-assist-chip>
<m3e-assist-chip variant="elevated">Elevated Assist</m3e-assist-chip>

The m3e-assist-chip provides a single slot, icon, to present an icon before a chip's label. Trailing icons are not supported for this chip type.

<m3e-assist-chip>
  <m3e-icon slot="icon" name="finance"></m3e-icon>
  Finance
</m3e-assist-chip>

Use the disabled attribute to disable an assist chip. By default, disabled chips are not focusable with the keyboard. You can use the disabled-interactive attribute to support focusability of disabled controls to increase their discoverability.

<m3e-assist-chip disabled>Disabled</m3e-assist-chip>
<m3e-assist-chip disabled-interactive>Disabled Interactive</m3e-assist-chip>

Use the type attribute to control the behavior of an assist chip. By default, type is button. You can change this to submit or reset to submit or reset a parenting form when clicked. When submitting a form, you can use the name and value attributes to specify a value.

Assist chips can also behave like links by specifying a URL using the href attribute. You can also specify target, rel and download similar to native anchor tags.

<m3e-assist-chip href="https://www.google.com" target="_blank">
  Google<
</m3e-assist-chip>

Use the m3e-filter-chip and m3e-filter-chip-set components to present chips that users can select or deselect to filter content or data sets.

<m3e-filter-chip-set>
  <m3e-filter-chip>Outlined</m3e-filter-chip>
  <m3e-filter-chip variant="elevated">Elevated</m3e-filter-chip>
</m3e-filter-chip-set>

The m3e-filter-chip provides slots for two icons. Use the icon slot to present an icon before a chip's label and use the trailing-icon slot to present an icon after it.

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

<m3e-filter-chip-set aria-label="Filter by topic">
  <m3e-filter-chip selected>
    <m3e-icon slot="icon" name="palette"></m3e-icon>Design
  </m3e-filter-chip>
  <!-- Additional chips omitted for brevity -->
</m3e-filter-chip-set>

Filter chips support both single-select and multi-select modes. Use the multi attribute of m3e-filter-chip-set to allow multiple chips to be selected simultaneously.

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

<m3e-filter-chip-set aria-label="Filter by topic" multi>
  <m3e-filter-chip selected>
    <m3e-icon slot="icon" name="palette"></m3e-icon>Design
  </m3e-filter-chip>
  <m3e-filter-chip selected>
    <m3e-icon slot="icon" name="accessibility_new"></m3e-icon>Accessibility
  </m3e-filter-chip>
  <!-- Additional chips omitted for brevity -->
</m3e-filter-chip-set>

Use the disabled attribute to disable a filter chip. By default, disabled chips are not focusable with the keyboard. You can use the disabled-interactive attribute to support focusability of disabled controls to increase their discoverability.

<m3e-filter-chip-set aria-label="Filter by topic">
  <m3e-filter-chip disabled>
    <m3e-icon slot="icon" name="palette"></m3e-icon>Design
  </m3e-filter-chip>
  <m3e-filter-chip disabled-interactive>
    <m3e-icon slot="icon" name="accessibility_new"></m3e-icon>Accessibility
  </m3e-filter-chip>
  <!-- Additional chips omitted for brevity -->
</m3e-filter-chip-set>

You can also use the disabled attribute of m3e-filter-chip-set to disable the chip set in its entirety.

<m3e-filter-chip-set aria-label="Filter by topic" multi disabled>
  <!-- Chips omitted for brevity -->
</m3e-filter-chip-set>

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

<m3e-filter-chip-set aria-label="Filter by topic" hide-selection-indicator>
  <m3e-filter-chip>Design </m3e-filter-chip>
  <m3e-filter-chip>Accessibility </m3e-filter-chip>
  <m3e-filter-chip><m3e-icon slot="icon" name="motion_photos_on"></m3e-icon>Motion </m3e-filter-chip>
  <m3e-filter-chip><m3e-icon slot="icon" name="description"></m3e-icon>Documentation </m3e-filter-chip>
</m3e-filter-chip-set>>

Filter chips 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 chip set's value is determined by selected chips. You can use the value of a m3e-filter-chip to control a chip's value. Otherwise, the value is derived from the chip's label (default slot). When multiple chips are selected, form data will include multiple entries keyed by the same name.

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

The m3e-input-chip-set component enables users to input, display, and manage a collection of discrete values as input chips. Designed for expressive, accessible forms, it supports keyboard navigation, validation, and seamless integration with m3e-form-field. See Form Field for more information.

Use the input slot of the m3e-input-chip-set to designate the input element associated with the component. When change is fired on the input, the chip set adds a new removable m3e-input-chip to the set. Users can press BACKSPACE to remove chips or click the remove button on individual chips. If a chip is focused, users can press DELETE to remove the chip.

The m3e-input-chip-set component raises a change event when chips are added to, or removed from, the set. You can use the value property to programmatically access the values of the chips in the set.

<m3e-form-field>
  <label slot="label" for="keywords">Keywords</label>
  <m3e-input-chip-set aria-label="Enter keywords">
    <input id="keywords" slot="input" placeholder="New keyword..." />
  </m3e-input-chip-set>
</m3e-form-field>

You can prepopulate a m3e-input-chip-set with chips using the m3e-input-chip component. Use the removable attribute to control whether a button is presented that allows the user to remove an input chip. This also controls whether BACKSPACE can be used to delete a chip using the keyboard.

<m3e-form-field>
  <label slot="label" for="keywords">Keywords</label>
  <m3e-input-chip-set aria-label="Enter keywords">
    <m3e-input-chip removable>Design</m3e-input-chip>
    <m3e-input-chip removable>Accessibility</m3e-input-chip>
    <m3e-input-chip removable>Motion</m3e-input-chip>
    <input id="keywords" slot="input" placeholder="New keyword..." />
  </m3e-input-chip-set>
</m3e-form-field>

Use the disabled attribute of m3e-input-chip-set to disable the chip set in its entirety, including its corresponding input and any prepopulated chips. In addition, chips cannot be removed when disabled.

<m3e-form-field>
  <label slot="label" for="keywords">Keywords</label>
  <m3e-input-chip-set aria-label="Enter keywords" disabled>
    <m3e-input-chip removable>Design</m3e-input-chip>
    <m3e-input-chip removable>Accessibility</m3e-input-chip>
    <m3e-input-chip removable>Motion</m3e-input-chip>
    <input id="keywords" slot="input" placeholder="New keyword..." />
  </m3e-input-chip-set>
</m3e-form-field>

Input chips 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 chip set's value is determined by its chips. When multiple chips are specified, form data will include multiple entries keyed by the same name.

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

Use the m3e-suggestion-chip component to offer users contextually relevant actions or responses. This component is visually and functionally equivalent to m3e-assist-chip, differing only in semantic intent. It encodes contextual suggestion rather than passive assistance, guiding user action through implied relevance.

<m3e-suggestion-chip>Outlined Suggestion</m3e-suggestion-chip>
<m3e-suggestion-chip variant="elevated">Elevated Suggestion</m3e-suggestion-chip>

The m3e-suggestion-chip provides a single slot, icon, to present an icon before a chip's label. Trailing icons are not supported for this chip type.

<m3e-suggestion-chip>
  <m3e-icon slot="icon" name="lightbulb"></m3e-icon>
  Try budget planner
</m3e-suggestion-chip>

Use the disabled attribute to disable a suggestion chip. By default, disabled chips are not focusable with the keyboard. You can use the disabled-interactive attribute to support focusability of disabled controls to increase their discoverability.

<m3e-suggestion-chip disabled>Disabled</m3e-suggestion-chip>
<m3e-suggestion-chip disabled-interactive>Disabled Interactive</m3e-suggestion-chip>

Use the type attribute to control the behavior of a suggestion chip. By default, type is button. You can change this to submit or reset to submit or reset a parenting form when clicked. When submitting a form, you can use the name and value attributes to specify a value.

Suggestion chips can also behave like links by specifying a URL using the href attribute. You can also specify target, rel and download similar to native anchor tags.

<m3e-suggestion-chip href="https://www.google.com" target="_blank">
  Google<
</m3e-suggestion-chip>

By default, m3e-chip and m3e-chip-set are not given an ARIA role, indicating that they are treated as neutral, non-semantic elements in the accessibility tree unless explicitly referenced or annotated.

Chip sets, regardless of variant (e.g., filter, input, suggestion), are annotated with aria-orientation="vertical" when rendered in a vertical layout. This attribute communicates directional flow to assistive technologies, ensuring spatial clarity and navigational predictability for screen reader users.

By default, action and suggestion chips are given the ARIA role button, indicating they are clickable elements that trigger actions. When href is specified, the ARIA role link is used instead of button to convey the chip provides an interactive reference to a resource. In addition, the chip presents an internal anchor, hidden from assistive technologies, used to invoke native browser features such a context menu options and tooltips.

When disabling using either the disabled or disabled-interactive attribute, aria-disabled="true" is used to convey to assistive technologies that the chip is disabled. If disabled using disabled-interactive, tabindex is retained to convey that the chip continues to be interactive.

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

Input chip sets are given ARIA role="grid" and chips are given role="row". Additionally, the internal content of an input chip (icons and label) are given ARIA role="gridcell" and the remove button's container is given role="gridcell". This pattern enables assistive technologies to interpret input chips as structured, interactive rows—enhancing clarity, predictability, and discoverability for users navigating via screen readers or keyboard.

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/chips/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.