sp-action-menu

Examples API

Attributes and Properties #

Property Attribute Type Default Description disabled disabled boolean false 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. 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.