sp-action-menu

Examples API

Attributes and Properties #

Property Attribute Type Default Description
autofocus autofocus boolean false When this control is rendered, focus it automatically
disabled disabled boolean false Disable this control. It will not receive focus or events
focused focused boolean false
icons icons 'only' | 'none' | undefined
invalid invalid boolean false
label label string | undefined
open open boolean false
placement placement "auto" | "auto-start" | "auto-end" | "top" | "bottom" | "right" | "left" | "top-start" | "top-end" | "bottom-start" | "bottom-end" | "right-start" | "right-end" | "left-start" | "left-end" | "none" 'bottom-start'
quiet quiet boolean false
readonly readonly boolean false
selects selects undefined | 'single' undefined By default `sp-action-menu` does not manage a selection. If you'd like for a selection to be held by the `sp-menu` that it presents in its overlay, use `selects="single" to activate this functionality.
size size ElementSize
tabIndex tabIndex number The tab index to apply to this control. See general documentation about the tabindex HTML property
value value string ''

Slots #

Name Description
default slot menu items to be listed in the Action Menu
icon The icon to use for Action Menu
label The label to use on for the Action Menu

Events #

Name Type Description
change Event Announces that the `value` of the element has changed
sp-closed Event Announces that the overlay has been closed
sp-opened Event Announces that the overlay has been opened

Description #

An <sp-action-menu> is an action button that triggers an overlay with <sp-menu-items> for activation. Use an <sp-menu> element to outline the items that will be made available to the user when interacting with the <sp-action-menu> element. By default <sp-action-menu> does not manage a selection. If you'd like for a selection to be held by the <sp-menu> that is presented in its overlay, use selects="single" to activate this functionality.

Usage #

See it on NPM! How big is this package in your project? Try it on webcomponents.dev

yarn add @spectrum-web-components/action-menu

Import the side effectful registration of <sp-action-menu> via:

import '@spectrum-web-components/action-menu/sp-action-menu.js';

The default of <sp-action-menu> will load dependencies in @spectrum-web-components/overlay asynchronously via a dynamic import. In the case that you would like to import those tranverse dependencies statically, import the side effectful registration of <sp-action-menu> as follows:

import '@spectrum-web-components/action-menu/sync/sp-action-menu.js';

When looking to leverage the ActionMenu base class as a type and/or for extension purposes, do so via:

import { ActionMenu } from '@spectrum-web-components/action-menu';

Sizes #

Small
<sp-action-menu size="s">
<span slot="label">More Actions</span>
<sp-menu-item>
Deselect
</sp-menu-item>
<sp-menu-item>
Select inverse
</sp-menu-item>
<sp-menu-item>
Feather...
</sp-menu-item>
<sp-menu-item>
Select and mask...
</sp-menu-item>
<sp-menu-divider></sp-menu-divider>
<sp-menu-item>
Save selection
</sp-menu-item>
<sp-menu-item disabled>
Make work path
</sp-menu-item>
</sp-action-menu>
Medium
<sp-action-menu size="m">
<span slot="label">More Actions</span>
<sp-menu-item>
Deselect
</sp-menu-item>
<sp-menu-item>
Select inverse
</sp-menu-item>
<sp-menu-item>
Feather...
</sp-menu-item>
<sp-menu-item>
Select and mask...
</sp-menu-item>
<sp-menu-divider></sp-menu-divider>
<sp-menu-item>
Save selection
</sp-menu-item>
<sp-menu-item disabled>
Make work path
</sp-menu-item>
</sp-action-menu>
Large
<sp-action-menu size="l">
<span slot="label">More Actions</span>
<sp-menu-item>
Deselect
</sp-menu-item>
<sp-menu-item>
Select inverse
</sp-menu-item>
<sp-menu-item>
Feather...
</sp-menu-item>
<sp-menu-item>
Select and mask...
</sp-menu-item>
<sp-menu-divider></sp-menu-divider>
<sp-menu-item>
Save selection
</sp-menu-item>
<sp-menu-item disabled>
Make work path
</sp-menu-item>
</sp-action-menu>
Extra Large
<sp-action-menu size="xl">
<span slot="label">More Actions</span>
<sp-menu-item>
Deselect
</sp-menu-item>
<sp-menu-item>
Select inverse
</sp-menu-item>
<sp-menu-item>
Feather...
</sp-menu-item>
<sp-menu-item>
Select and mask...
</sp-menu-item>
<sp-menu-divider></sp-menu-divider>
<sp-menu-item>
Save selection
</sp-menu-item>
<sp-menu-item disabled>
Make work path
</sp-menu-item>
</sp-action-menu>

Variants #

No visible label #

The visible label that is be provided via the default <slot> interface can be ommitted in preference of an icon only interface. In this context be sure that the <sp-action-menu> continued to be accessible to screen readers by applying the label attribute. This will apply an aria-label attribute of the same value to the <button> element that toggles the menu list.

<sp-action-menu label="More Actions">
<sp-menu-item>
Deselect
</sp-menu-item>
<sp-menu-item>
Select inverse
</sp-menu-item>
<sp-menu-item>
Feather...
</sp-menu-item>
<sp-menu-item>
Select and mask...
</sp-menu-item>
<sp-menu-divider></sp-menu-divider>
<sp-menu-item>
Save selection
</sp-menu-item>
<sp-menu-item disabled>
Make work path
</sp-menu-item>
</sp-action-menu>

Alternate icon #

A custom icon can be supplied via the icon slot in order to replace the default meatballs icon.

<sp-action-menu>
<sp-icon-settings slot="icon"></sp-icon-settings>
<span slot="label">Actions under the gear</span>
<sp-menu-item>
Deselect
</sp-menu-item>
<sp-menu-item>
Select inverse
</sp-menu-item>
<sp-menu-item>
Feather...
</sp-menu-item>
<sp-menu-item>
Select and mask...
</sp-menu-item>
<sp-menu-divider></sp-menu-divider>
<sp-menu-item>
Save selection
</sp-menu-item>
<sp-menu-item disabled>
Make work path
</sp-menu-item>
</sp-action-menu>

Selection. #

When selects is set to single, the <sp-action-menu> element will maintain one selected item after an initial selection is made.

<p>
The value of the `&lt;sp-action-menu&gt;` element is:
<span id="single-value"></span>
</p>
<sp-action-menu
selects="single"
onchange="this.previousElementSibling.querySelector('#single-value').textContent=this.value"
>

<span slot="label">Available shapes</span>
<sp-menu-item value="shape-1-square">Square</sp-menu-item>
<sp-menu-item value="shape-2-triangle">Triangle</sp-menu-item>
<sp-menu-item value="shape-3-parallelogram">Parallelogram</sp-menu-item>
<sp-menu-item value="shape-4-star">Star</sp-menu-item>
<sp-menu-item value="shape-5-hexagon">Hexagon</sp-menu-item>
<sp-menu-item value="shape-6-circle" disabled>Circle</sp-menu-item>
</sp-action-menu>

Accessibility #

An <sp-action-menu> parent will ensure that the internal <sp-menu> features a role of listbox and contains children with the role option. Upon focusing the <sp-action-menu> using ArrowDown will also open the menu while throwing focus into first selected (or unselected when none are selected) menu item to assist in selecting of a new value.