@m3e/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/lit@3.3.0/+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	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-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-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

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

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

🧩 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	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-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.