@m3e/menu

v1.2.2

Published

2 days ago

Menu for M3E

0High
0Medium
0Low

matraic

material design web components menu

@m3e/menu

The @m3e/menu package provides a cohesive set of components for constructing accessible, anchored menus that align with Material 3 design guidance. It supports both single and multi-selection patterns, nested menu hierarchies, and dynamically positioned floating panels. Menus are triggered from interactive elements and present checkable or exclusive choices using item variants. Grouping primitives establish selection boundaries, while nested flows support layered navigation and progressive disclosure.

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/menu

💻 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/menu, 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/menu/dist/html-custom-data.json"],
  "css.customData": ["./node_modules/@m3e/menu/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/menu/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",
      "@m3e/core/bidi": "/node_modules/@m3e/core/dist/bidi.js"
    }
  }
</script>

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

🗂️ Elements

m3e-menu — Presents a list of choices on a temporary surface.
m3e-menu-item — An item of a menu.
m3e-menu-item-checkbox — An item of a menu which supports a checkable state.
m3e-menu-item-radio — An item of a menu which supports a mutually exclusive checkable state.
m3e-menu-item-group — Groups related items (such a radios) in a menu.
m3e-menu-trigger — An element, nested within a clickable element, used to open a menu.

🧪 Examples

The following example illustrates a basic menu. The m3e-menu-trigger is used to trigger a m3e-menu specified by the for attribute when its parenting element is activated.

<m3e-button>
  <m3e-menu-trigger for="menu1">Basic menu</m3e-menu-trigger>
</m3e-button>
<m3e-menu id="menu1">
  <m3e-menu-item>Apple</m3e-menu-item>
  <m3e-menu-item>Apricot</m3e-menu-item>
  <m3e-menu-item>Avocado</m3e-menu-item>
  <m3e-menu-item>Green Apple</m3e-menu-item>
  <m3e-menu-item>Green Grapes</m3e-menu-item>
  <m3e-menu-item>Olive</m3e-menu-item>
  <m3e-menu-item>Orange</m3e-menu-item>
</m3e-menu>

The next example illustrates nested menus. Submenus are triggered by placing a m3e-menu-trigger inside a m3e-menu-item.

<m3e-button>
  <m3e-menu-trigger for="menu2">Nested menus</m3e-menu-trigger>
</m3e-button>
<m3e-menu id="menu2">
  <m3e-menu-item>
    <m3e-menu-trigger for="menu3">Fruits with A</m3e-menu-trigger>
  </m3e-menu-item>
  <m3e-menu-item>Grapes</m3e-menu-item>
  <m3e-menu-item>Olive</m3e-menu-item>
  <m3e-menu-item>Orange</m3e-menu-item>
</m3e-menu>
<m3e-menu id="menu3">
  <m3e-menu-item>Apricot</m3e-menu-item>
  <m3e-menu-item>Avocado</m3e-menu-item>
  <m3e-menu-item>
    <m3e-menu-trigger for="menu4">Apples</m3e-menu-trigger>
  </m3e-menu-item>
</m3e-menu>
<m3e-menu id="menu4">
  <m3e-menu-item>Fuji</m3e-menu-item>
  <m3e-menu-item>Granny Smith</m3e-menu-item>
  <m3e-menu-item>Red Delicious</m3e-menu-item>
</m3e-menu>

📖 API Reference

🗂️ m3e-menu

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

⚙️ Attributes

| Attribute | Type | Default | Description | | ------------ | --------------------------- | ------------ | ---------------------------------------- | | position-x | "before" | "after" | "after" | The position of the menu, on the x-axis. | | position-y | "above" | "below" | "below" | The position of the menu, on the y-axis. | | variant | "standard" | "vibrant" | "standard" | The appearance variant of the menu. |

🔔 Events

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

🧩 Slots

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

🎛️ CSS Custom Properties

| Property | Description | | ------------------------------------- | ------------------------------------------------------------- | | --m3e-menu-container-shape | Controls the corner radius of the menu container. | | --m3e-menu-active-container-shape | Controls the corner radius of the menu container when active. | | --m3e-menu-container-min-width | Minimum width of the menu container. | | --m3e-menu-container-max-width | Maximum width of the menu container. | | --m3e-menu-container-max-height | Maximum height of the menu container. | | --m3e-menu-container-padding-block | Vertical padding inside the menu container. | | --m3e-menu-container-padding-inline | Horizontal padding inside the menu container. | | --m3e-menu-container-color | Background color of the menu container. | | --m3e-menu-container-elevation | Box shadow elevation of the menu container. | | --m3e-vibrant-menu-container-color | Background color of the menu container for vibrant variant. | | --m3e-menu-divider-spacing | Vertical spacing around slotted m3e-divider elements. | | --m3e-menu-gap | Gap between content in the menu. |

🗂️ m3e-menu-item

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

⚙️ Attributes

| Attribute | Type | Default | Description | | ---------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------- | | disabled | boolean | false | Whether the element is disabled. | | download | string | | Whether the target of the link button will be downloaded, optionally specifying the new name of the file. | | href | string | | The URL to which the link button points. | | rel | string | | The relationship between the target of the link button and the document. | | target | string | | The target of the link button. |

🧩 Slots

| Slot | Description | | --------------- | ----------------------------------------- | | (default) | Renders the label of the item. | | icon | Renders an icon before the items's label. | | trailing-icon | Renders an icon after the item's label. |

🎛️ CSS Custom Properties

| Property | -------------------------------------------------------- | --m3e-menu-item-container-height | --m3e-menu-item-color | --m3e-menu-item-container-hover-color | --m3e-menu-item-container-focus-color | --m3e-menu-item-ripple-color | --m3e-menu-item-selected-color | --m3e-menu-item-selected-container-color | --m3e-menu-item-selected-container-hover-color | --m3e-menu-item-selected-container-focus-color | --m3e-menu-item-selected-ripple-color | --m3e-menu-item-active-state-layer-color | --m3e-menu-item-active-state-layer-opacity | --m3e-menu-item-disabled-color | --m3e-menu-item-disabled-opacity | --m3e-vibrant-menu-item-color | --m3e-vibrant-menu-item-container-hover-color | --m3e-vibrant-menu-item-container-focus-color | --m3e-vibrant-menu-item-ripple-color | --m3e-vibrant-menu-item-selected-color | --m3e-vibrant-menu-item-selected-container-color | --m3e-vibrant-menu-item-selected-container-h | --m3e-vibrant-menu-item-selected-container-f | --m3e-vibrant-menu-item-selected-ripple-color | --m3e-vibrant-menu-item-active-state-layer-color | --m3e-vibrant-menu-item-disabled-color | --m3e-menu-item-icon-label-space | --m3e-menu-item-padding-start | --m3e-menu-item-padding-end | --m3e-menu-item-label-text-font-size | --m3e-menu-item-label-text-font-weight | --m3e-menu-item-label-text-line-height | --m3e-menu-item-label-text-tracking | --m3e-menu-item-focus-ring-shape | --m3e-menu-item-icon-size | --m3e-menu-item-shape | --m3e-menu-item-first-child-shape | --m3e-menu-item-last-child-shape | Description | | ------------------------------------------------------------------ | | Height of the menu item container. | | Text color for unselected, enabled menu items. | | State layer hover color for unselected items. | | State layer focus color for unselected items. | | Ripple color for unselected items. | | Text color for selected items. | | Background color for selected items. | | State layer hover color for selected items. | | State layer focus color for selected items. | | Ripple color for selected items. | | State layer color for expanded items. | | State layer opacity for expanded items. | | Base color for disabled items. | | Opacity percentage for disabled item color mix. | | Text color for unselected, enabled menu items for vibrant variant. | | State layer hover color for unselected items for vibrant variant. | | State layer focus color for unselected items for vibrant variant. | | Ripple color for unselected items for vibrant variant. | | Text color for selected items for vibrant variant. | | Background color for selected items for vibrant variant. | over-color | State layer hover color for selected items for vibrant variant. | ocus-color | State layer focus color for selected items for vibrant variant. | | Ripple color for selected items for vibrant variant. | | State layer color for expanded items for vibrant variant. | | Base color for disabled items for vibrant variant. | | Horizontal gap between icon and content. | | Start padding for the item wrapper. | | End padding for the item wrapper. | | Font size for menu item text. | | Font weight for menu item text. | | Line height for menu item text. | | Letter spacing for menu item text. | | Border radius for the focus ring. | | Font size for leading and trailing icons. | | Base shape of the menu item. | | Shape for the first menu item in a menu. | | Shape for the last menu item in a menu. |

🗂️ m3e-menu-item-checkbox

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

⚙️ Attributes

| Attribute | Type | Default | Description | | ---------- | --------- | ------- | -------------------------------- | | disabled | boolean | false | Whether the element is disabled. | | checked | boolean | false | Whether the element is checked. |

🧩 Slots

🎛️ CSS Custom Properties

| Property | Description | | -------------------------------------------------------- | ------------------------------------------------------------------ | | --m3e-menu-item-container-height | Height of the menu item container. | | --m3e-menu-item-color | Text color for unselected, enabled menu items. | | --m3e-menu-item-container-hover-color | State layer hover color for unselected items. | | --m3e-menu-item-container-focus-color | State layer focus color for unselected items. | | --m3e-menu-item-ripple-color | Ripple color for unselected items. | | --m3e-menu-item-selected-color | Text color for selected items. | | --m3e-menu-item-selected-container-color | Background color for selected items. | | --m3e-menu-item-selected-container-hover-color | State layer hover color for selected items. | | --m3e-menu-item-selected-container-focus-color | State layer focus color for selected items. | | --m3e-menu-item-selected-ripple-color | Ripple color for selected items. | | --m3e-menu-item-active-state-layer-color | State layer color for expanded items. | | --m3e-menu-item-active-state-layer-opacity | State layer opacity for expanded items. | | --m3e-menu-item-disabled-color | Base color for disabled items. | | --m3e-menu-item-disabled-opacity | Opacity percentage for disabled item color mix. | | --m3e-vibrant-menu-item-color | Text color for unselected, enabled menu items for vibrant variant. | | --m3e-vibrant-menu-item-container-hover-color | State layer hover color for unselected items for vibrant variant. | | --m3e-vibrant-menu-item-container-focus-color | State layer focus color for unselected items for vibrant variant. | | --m3e-vibrant-menu-item-ripple-color | Ripple color for unselected items for vibrant variant. | | --m3e-vibrant-menu-item-selected-color | Text color for selected items for vibrant variant. | | --m3e-vibrant-menu-item-selected-container-color | Background color for selected items for vibrant variant. | | --m3e-vibrant-menu-item-selected-container-hover-color | State layer hover color for selected items for vibrant variant. | | --m3e-vibrant-menu-item-selected-container-focus-color | State layer focus color for selected items for vibrant variant. | | --m3e-vibrant-menu-item-selected-ripple-color | Ripple color for selected items for vibrant variant. | | --m3e-vibrant-menu-item-active-state-layer-color | State layer color for expanded items for vibrant variant. | | --m3e-vibrant-menu-item-disabled-color | Base color for disabled items for vibrant variant. | | --m3e-menu-item-icon-label-space | Horizontal gap between icon and content. | | --m3e-menu-item-padding-start | Start padding for the item wrapper. | | --m3e-menu-item-padding-end | End padding for the item wrapper. | | --m3e-menu-item-label-text-font-size | Font size for menu item text. | | --m3e-menu-item-label-text-font-weight | Font weight for menu item text. | | --m3e-menu-item-label-text-line-height | Line height for menu item text. | | --m3e-menu-item-label-text-tracking | Letter spacing for menu item text. | | --m3e-menu-item-focus-ring-shape | Border radius for the focus ring. | | --m3e-menu-item-icon-size | Font size for leading and trailing icons. | | --m3e-menu-item-shape | Base shape of the menu item. | | --m3e-menu-item-selected-shape | Shape used for a selected menu item. | | --m3e-menu-item-first-child-shape | Shape for the first menu item in a menu. | | --m3e-menu-item-last-child-shape | Shape for the last menu item in a menu. |

🗂️ m3e-menu-item-radio

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

⚙️ Attributes

🧩 Slots

🎛️ CSS Custom Properties

🗂️ m3e-menu-item-group

This section details the slots available for the m3e-menu-item-group component.

🧩 Slots

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

🗂️ m3e-menu-trigger

This section details the slots available for the m3e-menu-trigger component.

🧩 Slots

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

🤝 Contributing

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

📄 License

This package is licensed under the MIT License.

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

@m3e/menu

📦 Installation

💻 Editor Integration

Visual Studio Code

🚀 Native Module Support

🗂️ Elements

🧪 Examples

📖 API Reference

🗂️ m3e-menu

⚙️ Attributes

🔔 Events

🧩 Slots

🎛️ CSS Custom Properties

🗂️ m3e-menu-item

⚙️ Attributes

🧩 Slots

🎛️ CSS Custom Properties

🗂️ m3e-menu-item-checkbox

⚙️ Attributes

🧩 Slots

🎛️ CSS Custom Properties

🗂️ m3e-menu-item-radio

⚙️ Attributes

🧩 Slots

🎛️ CSS Custom Properties

🗂️ m3e-menu-item-group

🧩 Slots

🗂️ m3e-menu-trigger

🧩 Slots

🤝 Contributing

📄 License