On this page List List

The @m3e/list package provides expressive, accessible components for organizing and displaying lists of items.

Installation 
npm i @m3e/list
 Usage

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

Lists

To create a list of items, use the m3e-list component with one or more m3e-list-item components nested inside it.

Anatomy

The m3e-list-item component provides a modular layout for structured content blocks. It exposes the following named slots:

Overline Headline Supporting text 100+ 
<m3e-list>
  <m3e-list-item>
    <m3e-icon slot="leading" name="person"></m3e-icon>
    <span slot="overline">Overline</span>
    Headline
    <span slot="supporting-text">Supporting text</span>
    <span slot="trailing">100+</span>
  </m3e-list-item>
</m3e-list>
 Variants

There are two appearance variants standard (default) and segmented. Use the variant attribute to control a list's appearance.

Item 1 Item 2 Item 3 
<m3e-list>
  <m3e-list-item>Item 1</m3e-list-item>
  <!-- Additional items omitted for brevity -->
</m3e-list>

The following presents the segmented variant inside a filled card in order to illustrate color and shape.

Item 1 Item 2 Item 3 
<m3e-list variant="segmented">
  <m3e-list-item>Item 1</m3e-list-item>
  <!-- Additional items omitted for brevity -->
</m3e-list>
 Multiline items

List items are responsive containers that automatically adapt their height and internal spacing according to the item's line count, ensuring correct layout for one-line, two-line, and three-line configurations.

Label text Label text Supporting text Overline Label text Supporting text 
<m3e-list>
  <m3e-list-item>Label text</m3e-list-item>
  <m3e-list-item>
    Label text
    <span slot="supporting-text">Supporting text</span>
  </m3e-list-item>
  <m3e-list-item>
    <span slot="overline">Overline</span>
    Label text
    <span slot="supporting-text">Supporting text</span>
  </m3e-list-item>
</m3e-list>
 Media content

List items automatically size and position leading and trailing media—such as videos, images, avatars, and icons—according to the item's detected line count, reserving space when needed to keep visuals consistently aligned across one-, two-, and three-line configurations.

Label text Label text Supporting text Overline Label text Supporting text Label text 
<m3e-list>
  <m3e-list-item>
    <m3e-icon slot="leading" name="stars"></m3e-icon>
    Label text
    <m3e-icon slot="trailing" name="arrow_right"></m3e-icon>
  </m3e-list-item>
  <!-- Additional items omitted for brevity -->
</m3e-list>
AB Label text AB Label text Supporting text AB Overline Label text Supporting text Label text 
<m3e-list>
  <m3e-list-item>
    <m3e-avatar slot="leading">AB</m3e-avatar>
    Label text
    <m3e-icon slot="trailing" name="arrow_right"></m3e-icon>
  </m3e-list-item>
  <!-- Additional items omitted for brevity -->
</m3e-list>
Label text Label text Supporting text Overline Label text Supporting text Label text 
<m3e-list>
  <m3e-list-item>
    <img slot="leading" src="[YOUR IMAGE URL HERE]" />
    Label text
    <m3e-icon slot="trailing" name="arrow_right"></m3e-icon>
  </m3e-list-item>
  <!-- Additional items omitted for brevity -->
</m3e-list>
Label text Label text Supporting text Overline Label text Supporting text Label text 
<m3e-list>
  <m3e-list-item>
    <video slot="leading" autoplay loop poster="[YOUR IMAGE URL HERE]" preload="auto">
      <source src="[YOUR VIDEO URL HERE]" type="video/mp4"/>
    </video>
    Label text
    <m3e-icon slot="trailing" name="arrow_right"></m3e-icon>
  </m3e-list-item>
  <!-- Additional items omitted for brevity -->
</m3e-list>
 Dividers

The following example illustrates use of the m3e-divider to provide separators between items in a m3e-list. For more information on dividers, see Divider.

Dividers are only supported for the standard variant and are automatically hidden for segmented lists.

Item 1 Item 2 Item 3 
<m3e-list>
  <m3e-list-item>Item 1</m3e-list-item>
  <m3e-divider></m3e-divider>
  <m3e-list-item>Item 2</m3e-list-item>
  <m3e-divider></m3e-divider>
  <m3e-list-item>Item 3</m3e-list-item>
</m3e-list>

Dividers can also be inset using the inset attribute of a m3e-divider.

Item 1 Item 2 Item 3 
<m3e-list>
  <m3e-list-item>Item 1</m3e-list-item>
  <m3e-divider inset></m3e-divider>
  <!-- Additional items omitted for brevity -->
</m3e-list>
 Action lists

Use the m3e-action-list and m3e-list-action to create a list where each item performs a single action. Action lists support the same appearance variants as m3e-list and m3e-list-action supports the same slots as m3e-list-item.

Action 1 Action 2 Action 3 
<m3e-action-list>
  <m3e-list-action>Action 1</m3e-list-action>
  <!-- Additional actions omitted for brevity -->
</m3e-action-list>

The following presents the segmented variant inside a filled card in order to illustrate color and shape.

Action 1 Action 2 Action 3 
<m3e-action-list variant="segmented">
  <m3e-list-action>Action 1</m3e-list-action>
  <!-- Additional actions omitted for brevity -->
</m3e-action-list>
Disabling

Individual list actions can be disabled using the disabled attribute.

Disabled action 1 Action 2 Action 3 
<m3e-action-list>
  <m3e-list-action disabled>Disabled action 1</m3e-list-action>
  <!-- Additional actions omitted for brevity -->
</m3e-action-list>

The following presents the segmented variant inside a filled card in order to illustrate color and shape.

Disabled action 1 Action 2 Action 3 
<m3e-action-list variant="segmented">
  <m3e-list-action disabled>Disabled action 1</m3e-list-action>
  <!-- Additional actions omitted for brevity -->
</m3e-action-list>
Links

List actions 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.

Google 
<m3e-action-list>
  <m3e-list-action href="https://www.google.com" target="_blank">Google</m3e-list-action>
</m3e-action-list>
Nested lists

Both m3e-list and m3e-action-list can use an m3e-expandable-list-item to present hierarchical content that can be expanded or collapsed. The m3e-expandable-list-item provides a disclosure-style header that toggles the visibility of a nested list, allowing related actions or items to be grouped without overwhelming the parent list.

List item
List item List item List item
List item
List item List item List item
List item
List item List item List item 
<m3e-action-list>
  <m3e-expandable-list-item>
    <m3e-icon slot="leading" name="stars"></m3e-icon>
    List item
    <div slot="items">
      <m3e-list-action>
        <m3e-icon slot="leading" name="stars"></m3e-icon>
        List item
      </m3e-list-action>
      <!-- Additional actions omitted for brevity -->
    </div>
  </m3e-expandable-list-item>
  <!-- Additional items omitted for brevity -->
</m3e-action-list>

The following presents the segmented variant inside a filled card in order to illustrate color and shape.

List item
List item List item List item
List item
List item List item List item
List item
List item List item List item 
<m3e-action-list variant="segmented">
  <m3e-expandable-list-item>
    <m3e-icon slot="leading" name="stars"></m3e-icon>
    List item
    <div slot="items">
      <m3e-list-action>
        <m3e-icon slot="leading" name="stars"></m3e-icon>
        List item
      </m3e-list-action>
      <!-- Additional actions omitted for brevity -->
    </div>
  </m3e-expandable-list-item>
  <!-- Additional items omitted for brevity -->
</m3e-action-list>
Selection lists

Use the m3e-selection-list and m3e-list-option to create a list for selecting values, where each item performs a single option. Selection lists support the same appearance variants as m3e-list and m3e-list-option supports the same slots as m3e-list-item. However, the selection indicator will replaces content in the trailing slot unless selection indicators are hidden.

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

Option 1 Option 2 Option 3 
<m3e-selection-list>
  <m3e-list-option>Option 1</m3e-list-option>
  <!-- Additional options omitted for brevity -->
</m3e-selection-list>

The following presents the segmented variant inside a filled card in order to illustrate color and shape.

Option 1 Option 2 Option 3 
<m3e-selection-list variant="segmented">
  <m3e-list-option>Option 1</m3e-list-option>
  <!-- Additional options omitted for brevity -->
</m3e-selection-list>
Multiple selection

Selection lists support both single-select and multi-select modes. Use the multi attribute to allow multiple options to be selected simultaneously.

Option 1 Option 2 Option 3 
<m3e-selection-list multi>
  <m3e-list-option>Option 1</m3e-list-option>
  <!-- Additional options omitted for brevity -->
</m3e-selection-list>

The following presents the segmented variant inside a filled card in order to illustrate color and shape.

Option 1 Option 2 Option 3 
<m3e-selection-list variant="segmented" multi>
  <m3e-list-option>Option 1</m3e-list-option>
  <!-- Additional options omitted for brevity -->
</m3e-selection-list>
Hiding the selection indicator

Use the hide-selection-indicator attribute of m3e-selection-list to hide selection indicators. If an option has an icon via use of the trailing slot, the icon is presented.

Option 1 Option 2 Option 3 
<m3e-selection-list multi hide-selection-indicator>
  <m3e-list-option selected>Option 1<m3e-icon slot="trailing" name="bookmark"></m3e-icon></m3e-list-option>
  <m3e-list-option>Option 2<m3e-icon slot="trailing" name="bookmark"></m3e-icon></m3e-list-option>
  <m3e-list-option>Option 3<m3e-icon slot="trailing" name="bookmark"></m3e-icon></m3e-list-option>
</m3e-selection-list>
Disabling

Individual list options can be disabled using the disabled attribute and can be selected and disabled.

Option 1 Option 2 Option 3 
<m3e-selection-list multi>
  <m3e-list-option disabled>Option 1</m3e-list-option>
  <m3e-list-option selected disabled>Option 1</m3e-list-option>
  <!-- Additional options omitted for brevity -->
</m3e-selection-list>

The following presents the segmented variant inside a filled card in order to illustrate color and shape.

Option 1 Option 2 Option 3 
<m3e-selection-list variant="segmented" multi>
  <m3e-list-option disabled>Option 1</m3e-list-option>
  <m3e-list-option selected disabled>Option 1</m3e-list-option>
  <!-- Additional options omitted for brevity -->
</m3e-selection-list>
Form Associated

Selection lists 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 list's value is determined by selected options. You can use the value of a m3e-list-option to control a option's value. When multiple options are selected, form data will include multiple entries keyed by the same name.

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

Accessibility

Lists are given the ARIA role="list" and list items are given role="listitem" to ensure that assistive technologies can correctly interpret the structure and semantics of the content.

Action lists are given the ARIA role="list" and list actions are given role="listitem" to ensure that assistive technologies can correctly interpret the structure and semantics of the content. Each list action includes a nested interactive element with ARIA role="button". When href is specified, the ARIA role link is used instead of button to convey the list action provides an interactive reference to a resource. In addition, the component presents an internal anchor, hidden from assistive technologies, used to invoke native browser features such a context menu options and tooltips. When disabled using the disabled attribute, aria-disabled="true" is applied to the nested interactive element in order to convey to assistive technologies that the action is disabled.

Selection lists are given the ARIA role="listbox" and options are given role="option" to ensure that assistive technologies recognize the widget as a selectable list and expose the correct interaction model to users. The aria-selected attribute reflects whether an option is currently selected. When an option is selected, aria-selected="true" is exposed to assistive technologies; otherwise, it is "false". When disabled using the disabled attribute, aria-disabled="true" is applied to the option in order to convey to assistive technologies that the option is disabled. When multi-select is enabled through the multi attribute, aria-multiselectable="true" is applied to the selection list indicating multiple options can be selected.

Expandable list items use ARIA role="listitem"> and emulate the behavior of the native details and summary elements. Inside each item, the header is assigned role="button"> along with an aria-controls attribute referencing the item's internal content wrapper. The content wrapper is given role="list"> to represent the nested list of child items. The header's aria-expanded attribute reflects the current expanded or collapsed state of the item.

Native module support

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

API

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.