@m3e/option

The m3e-option, m3e-option-panel, and m3e-optgroup components provide a complete solution for displaying selectable options in menus and lists. They follow Material Design 3 principles with comprehensive support for single and multiple selection, dynamic positioning, keyboard navigation, and extensive theming via CSS custom properties.

This package is part of M3E monorepo, a unified suite of Material 3 web components. Explore the docs to see them in action.

📦 Installation

npm install @m3e/option

💻 Editor Integration

This package includes a Custom Elements Manifest to support enhanced editor tooling and developer experience.

Visual Studio Code

To enable autocomplete and hover documentation for @m3e/option, install the Custom Elements Manifest Language Server extension. It will automatically detect the manifest bundled with this package and surface tag names, attributes, slots, and events in supported files.

Alternately, you can explicitly reference the html-custom-data.json and css-custom-data.json in your workspace settings:

{
  "html.customData": ["./node_modules/@m3e/option/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/option/dist/css-custom-data.json"]
}

🚀 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/option/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/[email protected]/+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"
    }
  }
</script>

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

🗂️ Elements

• m3e-option — A selectable item within a menu or list, providing visual feedback and selection state management.
• m3e-option-panel — A temporary surface that presents a scrollable list of options anchored to a trigger element.
• m3e-optgroup — A container that groups related options under a customizable label with semantic structure.

🧪 Example

<m3e-option-panel>
  <m3e-option value="apple">Apple</m3e-option>
  <m3e-option value="banana">Banana</m3e-option>
  <m3e-optgroup>
    <span slot="label">Citrus</span>
    <m3e-option value="lemon">Lemon</m3e-option>
    <m3e-option value="orange">Orange</m3e-option>
  </m3e-optgroup>
</m3e-option-panel>

📖 API Reference

🗂️ m3e-option

This section details the attributes, slots, events and CSS custom properties available for the m3e-option component.

⚙️ Attributes

| Attribute | Type | Default | Description | | ---------- | --------- | ------- | ---------------------------------------------- | | disabled | boolean | false | Whether the element is disabled. | | selected | boolean | false | Whether the element is selected. | | value | string | | A string representing the value of the option. |

🧩 Slots

| Slot | Description | | ----------- | -------------------------------- | | (default) | Renders the label of the option. |

🎛️ CSS Custom Properties

| Property | Description | | --------------------------------------------- | ------------------------------------------------- | | --m3e-option-container-height | The height of the option container. | | --m3e-option-color | The text color of the option. | | --m3e-option-container-hover-color | The color for the hover state layer. | | --m3e-option-container-focus-color | The color for the focus state layer. | | --m3e-option-ripple-color | The color of the ripple effect. | | --m3e-option-selected-color | The text color when the option is selected. | | --m3e-option-selected-container-color | The background color when the option is selected. | | --m3e-option-selected-container-hover-color | The hover color for the selected state layer. | | --m3e-option-selected-container-focus-color | The focus color for the selected state layer. | | --m3e-option-selected-ripple-color | The ripple color when the option is selected. | | --m3e-option-disabled-color | The text color when the option is disabled. | | --m3e-option-disabled-opacity | The opacity level applied to the disabled text. | | --m3e-option-icon-label-space | The spacing between the icon and label. | | --m3e-option-padding-start | The left padding of the option content. | | --m3e-option-padding-end | The right padding of the option content. | | --m3e-option-label-text-font-size | The font size of the option label. | | --m3e-option-label-text-font-weight | The font weight of the option label. | | --m3e-option-label-text-line-height | The line height of the option label. | | --m3e-option-label-text-tracking | The letter spacing of the option label. | | --m3e-option-focus-ring-shape | The corner radius of the focus ring. | | --m3e-option-icon-size | The size of the option icons. |

🗂️ m3e-option-panel

This section details the attributes, slots, events and CSS custom properties available for the m3e-option-panel component.

🔔 Events

| Event | Description | | -------------- | ---------------------------------------------- | | beforetoggle | Dispatched before the toggle state changes. | | toggle | Dispatched after the toggle state has changed. |

🧩 Slots

| Slot | Description | | ----------- | --------------------------------- | | (default) | Renders the contents of the list. |

🎛️ CSS Custom Properties

| Property | Description | | -------------------------------------------- | ------------------------------------------------------- | | --m3e-option-panel-container-shape | Controls the corner radius of the menu container. | | --m3e-option-panel-container-min-width | Minimum width of the menu container. | | --m3e-option-panel-container-max-width | Maximum width of the menu container. | | --m3e-option-panel-container-max-height | Maximum height of the menu container. | | --m3e-option-panel-container-padding-block | Vertical padding inside the menu container. | | --m3e-option-panel-container-color | Background color of the menu container. | | --m3e-option-panel-container-elevation | Box shadow elevation of the menu container. | | --m3e-option-panel-divider-spacing | Vertical spacing around slotted m3e-divider elements. |

🗂️ m3e-optgroup

This section details the attributes, slots, and CSS custom properties available for the m3e-optgroup component.

🧩 Slots

| Slot | Description | | ----------- | --------------------------------- | | (default) | Renders the options of the group. | | label | Renders the label of the group. |

🎛️ CSS Custom Properties

| Property | Description | | ---------------------------- | ---------------------------------------- | | --m3e-option-height | The height of the group label container. | | --m3e-option-font-size | The font size of the group label. | | --m3e-option-font-weight | The font weight of the group label. | | --m3e-option-line-height | The line height of the group label. | | --m3e-option-tracking | The letter spacing of the group label. | | --m3e-option-padding-end | The right padding of the label. | | --m3e-option-padding-start | The left padding of the label. | | --m3e-option-color | The text color of the group label. |

🤝 Contributing

See the root monorepo CONTRIBUTING.md for guidelines on contributing to this package.

📄 License

This package is licensed under the MIT License.