🚀 DAY 5 OF LAUNCH WEEK: Introducing Socket Firewall Enterprise.Learn more →

Book a Demo Install Sign in

@spectrum-web-components/menu

Package Overview

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

@spectrum-web-components/menu

An `<sp-menu>` is used for creating a menu list. The various elements inside a menu are given as [`<sp-menu-group>`](../menu-group), [`<sp-menu-item>`](../menu-item), or `<sp-menu-divider>`. Often a `<sp-menu>` element will appear in a [`<sp-popover>`](..

Source

npm

Version: 1.8.0

Version published: last month

Maintainers: 7

Created: 6 years ago

Source

Overview

An <sp-menu> is used for creating a menu list. The various elements inside a menu are given as <sp-menu-group>, <sp-menu-item>, or <sp-menu-divider>. Often a <sp-menu> element will appear in a <sp-popover> element so that it displays as a toggling menu.

Usage

yarn add @spectrum-web-components/menu

Import the side effectful registration of <sp-menu>, <sp-menu-group>, <sp-menu-item>, or <sp-menu-divider> individually as follows:

import '@spectrum-web-components/menu/sp-menu.js';
import '@spectrum-web-components/menu/sp-menu-group.js';
import '@spectrum-web-components/menu/sp-menu-item.js';
import '@spectrum-web-components/menu/sp-menu-divider.js';

When looking to leverage the Menu, MenuGroup, MenuItem, or MenuDivider base classes as a type and/or for extension purposes, do so via:

import {
    Menu,
    MenuGroup,
    MenuItem,
    MenuDivider
} from '@spectrum-web-components/menu';

Anatomy

<sp-menu label="Selection type">
    <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-item>
        Save selection
    </sp-menu-item>
    <sp-menu-item disabled>
        Make work path
    </sp-menu-item>
</sp-menu>

Often an <sp-menu> element will be delivered inside of an <sp-popover> element when displaying it above other content.

<sp-popover open style="position: relative" label="Selection type">
    <sp-menu>
        <sp-menu-item value="item-1">Deselect</sp-menu-item>
        <sp-menu-item value="item-2">Select inverse</sp-menu-item>
        <sp-menu-item value="item-3">Feather...</sp-menu-item>
        <sp-menu-item value="item-4">Select and mask...</sp-menu-item>
        <sp-menu-item value="item-5">Save selection</sp-menu-item>
        <sp-menu-item value="item-6" disabled>Make work path</sp-menu-item>
    </sp-menu>
</sp-popover>

Labels

To render accessibly, an <sp-menu> element or its parent <sp-popover> must have a label. For an accessible label that is visibly hidden, but can still be read by assistive technology, use the label attribute.

Menu with label

<sp-menu id="menu-label-attribute" label="Selection type">
    <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-menu>

Popover with label

<sp-popover open style="position: relative" label="Selection type:">
    <sp-menu id="popover-label-attribute">
        <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-menu>
</sp-popover>

Options

Sizes

Small

<sp-menu id="menu-s" size="s" label="Selection type">
    <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-menu>
<sp-popover open style="position: relative" label="Selection type:">
    <sp-menu id="menu-s-popover" size="s">
        <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-menu>
</sp-popover>

Medium

<sp-menu id="menu-m" size="m" label="Selection type">
    <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-menu>
<sp-popover open style="position: relative" label="Selection type:">
    <sp-menu id="menu-m-popover" size="m">
        <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-menu>
</sp-popover>

Large

<sp-menu id="menu-l" size="l" label="Selection type">
    <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-menu>
<sp-popover open style="position: relative" label="Selection type:">
    <sp-menu id="menu-l-popover" size="l">
        <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-menu>
</sp-popover>

Extra Large

<sp-menu id="menu-xl" size="xl" label="Selection type">
    <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-menu>
<sp-popover open style="position: relative" label="Selection type:">
    <sp-menu id="menu-xl-popover" size="xl">
        <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-menu>
</sp-popover>

Selection

The <sp-menu> element can be instructed to maintain a selection via the selects attribute. Depending on the chosen algorithm, the <sp-menu> element will hold a value property and manage the selected state of its <sp-menu-item> descendants.

When selects="single", the <sp-menu> element will maintain one selected item after an initial selection is made.
When selects is set to multiple, the <sp-menu> element will maintain zero or more selected items.
When selects is set to inherit, the <sp-menu> element will allow its <sp-menu-item> children to participate in the selection of its nearest <sp-menu> ancestor.

Single

<p>
    The value of the `&lt;sp-menu&gt;` element is:
    <span id="single-value"></span>
</p>
<sp-menu
    label="Choose a shape"
    selects="single"
    onchange="this.previousElementSibling.querySelector('#single-value').textContent=this.value"
>
    <sp-menu-item value="item-1">Square</sp-menu-item>
    <sp-menu-item value="item-2" selected>Triangle</sp-menu-item>
    <sp-menu-item value="item-3">Parallelogram</sp-menu-item>
    <sp-menu-item value="item-4">Star</sp-menu-item>
    <sp-menu-item value="item-5">Hexagon</sp-menu-item>
    <sp-menu-item value="item-6" disabled>Circle</sp-menu-item>
</sp-menu>

Multiple

<p>
    The value of the `&lt;sp-menu&gt;` element is:
    <span id="multiple-value">item-3,item-4</span>
</p>
<sp-menu
    label="Choose some fruit"
    selects="multiple"
    onchange="this.previousElementSibling.querySelector('#multiple-value').textContent=this.value"
>
    <sp-menu-item value="item-1">Apple</sp-menu-item>
    <sp-menu-item value="item-2">Banana</sp-menu-item>
    <sp-menu-item value="item-3" selected>Goji berry</sp-menu-item>
    <sp-menu-item value="item-4" selected>Grapes</sp-menu-item>
    <sp-menu-item value="item-5" disabled>Kumquat</sp-menu-item>
    <sp-menu-item value="item-6">Orange</sp-menu-item>
</sp-menu>

Inherit

<p>
    The value of the `&lt;sp-menu&gt;` element is:
    <span id="inherit-value">item-3 || item-4 || item-8 || item-11</span>
</p>
<sp-menu
    label="Choose some groceries"
    selects="multiple"
    value-separator=" || "
    onchange="this.previousElementSibling.querySelector('#inherit-value').textContent=this.value"
>
    <sp-menu label="Fruit" selects="inherit">
        <sp-menu-item value="item-1">Apple</sp-menu-item>
        <sp-menu-item value="item-2">Banana</sp-menu-item>
        <sp-menu-item value="item-3" selected>Goji berry</sp-menu-item>
        <sp-menu-item value="item-4" selected>Grapes</sp-menu-item>
        <sp-menu-item value="item-5" disabled>Kumquat</sp-menu-item>
        <sp-menu-item value="item-6">Orange</sp-menu-item>
    </sp-menu>
    <sp-menu label="Vegetables" selects="inherit">
        <sp-menu-item value="item-7">Carrot</sp-menu-item>
        <sp-menu-item value="item-8" selected>Garlic</sp-menu-item>
        <sp-menu-item value="item-9" disabled>Lettuce</sp-menu-item>
        <sp-menu-item value="item-10">Onion</sp-menu-item>
        <sp-menu-item value="item-11" selected>Potato</sp-menu-item>
        <sp-menu-item value="item-12">Tomato</sp-menu-item>
    </sp-menu>
</sp-menu>

Behaviors

"change" event

Regardless of whether or not <sp-menu> carries a selection, when one of the <sp-menu-item> children that it manages is activated, the <sp-menu> element will dispatch a change event. At dispatch time, even when a selection is not held due to the absence of the selects attribute, the value of the <sp-menu> will correspond to the <sp-menu-item> that was activated. When the selects attribute is present, this value will persist beyond the lifecycle of the change event. When selects="multiple", the values of multiple items will be comma separated, unless otherwise set via the value-separator attribute.

Note: The change event is only dispatched on a left mouse click or Enter/Space keypress. Right/Middle mouse clicks will not dispatch the change event.

Accessibility

Review the accessibility guidelines for the menu-item and menu-group descendants.

Include a label

A menu is required to have an accessible label.

1.8.0 (2025-09-23)

Minor Changes

sp-picker: Fixed escape key behavior in modal overlays containing picker components. Previously, pressing the Escape key when a picker was open inside a modal overlay would not properly close the modal, instead moving focus to the picker. Now, the escape key correctly closes the picker first (if open), then closes the modal overlay on subsequent escape key presses.

This fix adds a check for this.open in the picker's handleEscape method to ensure proper modal overlay closure behavior.

sp-overlay: Added allow-outside-click property to <sp-overlay> with deprecation notice. This property allows clicks outside the overlay to close it, but is not recommended for accessibility reasons and will be removed in a future version.

This property is being added as deprecated to support the fallback for showModal() which was removed as part of performance optimization. We will no longer support outside clicks for modal overlays as they violate accessibility guidelines.

The property defaults to false and shows deprecation warnings when used. Consider using explicit close buttons or modal/page overlay types instead for better accessibility.

sp-menu: Fixed : Fix iPad scrolling issue in picker dropdown where scrolling through menu items would accidentally select the first touched item and close the picker.

The fix implements touch gesture detection to distinguish between scrolling and selection. Added isScrolling getter for public API access. Test on iPad devices with long menus to validate scrolling behavior and selection accuracy.

sp-overlay: Fixed : Added body scroll prevention for modal and page overlays. Overlay automatically blocks body scroll when modal or page overlays are open and restores the original scroll state when they are closed, improving user experience and accessibility for modal dialogs.

sp-clear-button: Clear button styles have been updated to the latest Spectrum CSS version of the clear button. This update includes a major reduction in the number of custom property abstractions needed to support the multiple theming layers (as seen in the styles package).

This update spans the following additional packages:

@spectrum-web-components/button
@spectrum-web-components/styles

As the updated styles now offer additional styling options, we have added the following API to the clear button component that exists in the button package:

quiet - when set to true, the button will be rendered as a quiet button. This is useful for cases where you want to use the clear button in a more subtle way.
disabled - when set to true, the button will be rendered as a disabled button.
static-color - currently this only supports the white context color. This is useful for cases where the button appears on a dark background texture. This is a replacement for the previously used variant="overBackground" attribute which is deprecated.

Deprecation

The variant="overBackground" attribute is deprecated; please use the new static-color="white" attribute instead. When this property is used in the component, a deprecation warning will be shown in the console when in debug mode. The variant attribute will be removed in a future release.

sp-card: Fixed the card component's CSS by moving block-size: 100% from the base :host selector to only apply to gallery and quiet variants

sp-overlay: Fixed : external click registration behavior in the sp-overlay component. Programmatic clicks on elements outside of modal overlays now properly register and close the overlay, while user-initiated clicks are prevented from doing so.

sp-card: Enhanced the Card component's checkbox functionality with improved screen reader support and keyboard navigation.

Patch Changes

sp-progress-bar: Added: Deprecation warning for the over-background attribute.

sp-combobox: Replace the use of offsetWidth with a resizeObserver to avoid unecessary, performance-impacting layout reflows.

sp-styles: Bring the CJK font alias token fix from CSS #3883 4e3a120.

The --spectrum-cjk-font token was incorrectly mapped to the code font-family stack instead of --spectrum-cjk-font-family-stack. Thanks @byteakp!

sp-color-wheel: Fixed <sp-color-wheel> step attribute functionality for keyboard navigation. The step attribute now properly controls the increment size when using arrow keys to navigate the color wheel.

sp-switch: ### Fix down state colors for switch

Because the postcss-hover-media-feature plugin converts hover styles into a media query for devices that support hover, the hover styles were overriding any active/down state styles. We needed to target the active/down states of the switch with additional active state selectors, in order to ensure that the active state takes precedence over the hover state, maintaining the correct visual behavior of the switch component across different interaction states.

This fix should address hover + active state discrepancies in S1 and S2 foundations.

sp-contextual-help: Fixed a typo in the default info variant label from "Informations" to "Information".

Additionally, added package dependency for @spectrum-web-components/reactive-controllers@1.7.0.

sp-slider: Editable sliders will now reliably emit input events when interaction starts with the track.

sp-link: Fixed quiet variant links not showing keyboard focus state in Safari. Links with the quiet attribute now properly display focus indicators when navigating with keyboard, improving accessibility for keyboard users.

sp-progress-bar: Smooths the transition animation of indeterminate progress bar by overriding the incoming CSS, and positioning the animating fill element completely off of the progress bar track in both LTR and RTL languages. Before, the fill element was automatically starting on the track which led to a jarring animation loop.

sp-divider: Added: staticColor property to the Divider component, enabling programmatic control of the existing static color functionality.

Keywords

FAQs

Package last updated on 23 Sep 2025

Did you know?

Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.

Install

@spectrum-web-components/menu

Overview

Usage

Anatomy

Popover menus

Labels

Options

Sizes

Selection

Behaviors

"change" event

Accessibility

Include a label

1.8.0 (2025-09-23)

Minor Changes

Deprecation

Patch Changes

Keywords

Related posts

@spectrum-web-components/menu

Overview

Usage

Anatomy

Popover menus

Labels

Options

Sizes

Selection

Behaviors

"change" event

Accessibility

Include a label

1.8.0 (2025-09-23)

Minor Changes

Deprecation

Patch Changes

Keywords

Related posts

New CNAPulse Dashboard Tracks CNA Activity and Disclosure Trends

Introducing GitHub Actions Scanning Support