Components / Library version 3.25.1

Action Menu

This component provides a dropdown menu of action items. When closed, it displays a text-only button, icon-only button, or a selector box. Selecting a menuitem completes the associated action and closes the menu. It should have at least one menuitem component as a child.

After an action is executed make sure to properly handle focus for accessibility reasons.

Properties Examples Events Accessibility Notes

** Required in certain cases

action-menu-type
icon | text | selector | selector-primary
Indicates whether the anchoring button should be an icon, text, or style of selector box. Defaults to icon.

Properties for each Action Menu type:

tooltip: Required tooltip-position: Optional label-for-identical-buttons: SEE DETAILS BELOW disabled: Optional buttonText: Required disabled: Optional buttonText: Required disabled: Optional dark-mode: Optional buttonText: Required disabled: Optional dark-mode: Optional
button-text **
string
Indicates the text to display for the text or selector action menu. Required when button-type is text or selector.
dark-mode
boolean
Set dark mode for selector and selector-primary.
tooltip **
string
Indicates the text to display in the tooltip for the icon action menu. Required when button-type is icon. It should indicate the name or purpose of the menu.
tooltip-position
top | bottom | left | right | top-left | top-right | bottom-left | bottom-right
Sets the position of the tooltip. Defaults to left. If there is not enough space to display the tooltip at the indicated position, the component will automatically reposition it.
label-for-identical-buttons
string
Use only in this specific case:
If a page has several icon action menus with an identical tooltips, the aria-label of the button needs to include more descriptive information than the tooltip displayed. In that case, set this prop to the more descriptive name, and leave the tooltip prop unchanged.
disabled
boolean
The selector menu can be disabled as a whole (rather than just individual menuitems).

For the properties of the children, see menuitem.

Deprecated properties

button-type
icon | text | selector
Deprecated in favor of action-menu-type. Previously, indicates whether the anchoring button should be an icon, text, or selector box.

Usage in HTML

Edit the code below to see changes reflected in the example above.

Usage in Elm

Code generated from HTML.
wmActionMenuLoaded
Emitted when the menu has finished loading.

General

The "tooltip" property required for icon action menus ensures that the name or purpose of the menu is apparent on hover and announced by screenreaders.

Keyboard Support

Key Function
Down Arrow Space Enter Opens menu and moves focus to first menuitem.
Down Arrow Space Enter Opens menu and moves focus to last menuitem.
Key Function
Enter
  • Activates the menuitem, causing the "onclick" function passed to it to run.
  • Closes the menu.
  • Sets focus on the menu button.
Escape
  • Closes the menu.
  • Sets focus to the menu button.
Up Arrow
  • Moves focus to the previous menuitem.
  • If focus is on the first menuitem, moves focus to the last menuitem.
Down Arrow
  • Moves focus to the next menuitem.
  • If focus is on the last menuitem, moves focus to the first menuitem.
Home Moves focus to the first menuitem.
End Moves focus to the last menuitem.
A-Z a-z
  • Moves focus to the next menuitem with a label that starts with the typed character if such a menuitem exists.
  • Otherwise, focus does not move.
  • When a menuitem is clicked, an attribute is temporarily added to the body. The attribute is used to reapply focus when a new menu is loaded with updated menuitems.
  • Depending on context, screen readers may not announce the expanded state. This is normal behavior and does not constitutes an accessibility issue.

In a compound component like Select or Action Menu, child components are rendered in the parent's slot element, part of its shadow DOM tree. Slots essentially serve as a placeholder for markup that you the developer define in the light DOM tree, like <wm-menuitem>, <wm-option>, text content, or other child elements.

The browser distributes the child elements defined in the light DOM into the shadow DOM of the parent. The result is a flattened DOM tree—a merger of the the light DOM and the shadow DOM. This flattened tree is what you see in DevTools and what is rendered on the page.

With the standard implementation of the component, dynamically updating the child items will throw an error. Elm's efficient diffing of the DOM will register that only the child items have changed and try to update them, but the component has already been composed.

Rendering the component in a Keyed node and giving it a dynamic id will cause the entire component, rather than just the child items, to render anew, avoiding the error.