sp-menu-group

NPM 1.0.1

View Storybook

Try it on webcomponents.dev
Overview API

Overview

An <sp-menu-group> will gather a collection of <sp-menu-item> elements into a group as part of the content delivered in an <sp-menu> element. Supplying content to the header slot will allow it label the group both visually and for screen readers. Like <sp-menu>, an <sp-menu-group> element can maintain a selection as outlined by the value or absence of its selects attribute.

Usage

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

yarn add @spectrum-web-components/menu

Import the side effectful registration of <sp-menu-group> as follows:

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

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

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

Anatomy

An <sp-menu-group> can be used to organize <sp-menu-item> elements in an <sp-memu> into collections with a shared header. Use an element addressed to the slot="header" to pass in the content of that header.

<sp-menu label="What are your favorite parks?">
        <sp-menu-group>
            <span slot="header">New York</span>
            <sp-menu-item>
                Central Park
            </sp-menu-item>
            <sp-menu-item>
                Flushing Meadows Corona Park
            </sp-menu-item>
            <sp-menu-item>
                Prospect Park
            </sp-menu-item>
        </sp-menu-group>
        <sp-menu-group>
            <span slot="header">San Francisco</span>
            <sp-menu-item>
                Golden Gate Park
            </sp-menu-item>
            <sp-menu-item>
                John McLaren Park
            </sp-menu-item>
            <sp-menu-item>
                Lake Merced Park
            </sp-menu-item>
        </sp-menu-group>
    </sp-menu>
</sp-popover>

Behavior

Selection

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

  • When selects is set to single, the <sp-menu-group> element will maintain one selected item after an initial selection is made.
  • When selects is set to multiple, the <sp-menu-group> element will maintain zero or more selected items.
  • When selects is set to inherit, the <sp-menu-group> element will allow its <sp-menu-item> children to participate in the selection of its nearest <sp-menu> ancestor.
Single 
<p>
    Your favorite park in New York is: <span id="single-group-1-value"></span>
    <br><br>
    Your favorite park in San Francisco is: <span id="single-group-2-value"></span>
</p>
<sp-popover open style="position: relative">
    <sp-menu
        label="What are your favorite parks?"
        style="width: 200px"
        onchange="this.parentElement
                    .previousElementSibling
                    .querySelector(`#${arguments[0].target.id}-value`)
                    .textContent = arguments[0].target.value">
        <sp-menu-group
            id="single-group-1"
            selects="single"
        >
            <span slot="header">New York</span>
            <sp-menu-item>
                Central Park
            </sp-menu-item>
            <sp-menu-item>
                Flushing Meadows Corona Park
            </sp-menu-item>
            <sp-menu-item>
                Prospect Park
            </sp-menu-item>
        </sp-menu-group>
        <sp-menu-group
            id="single-group-2"
            selects="single"
        >
            <span slot="header">San Francisco</span>
            <sp-menu-item>
                Golden Gate Park
            </sp-menu-item>
            <sp-menu-item>
                John McLaren Park
            </sp-menu-item>
            <sp-menu-item>
                Lake Merced Park
            </sp-menu-item>
        </sp-menu-group>
    </sp-menu>
</sp-popover>
 Multiple 
<p>
    Your favorite parks in New York are: <span id="multiple-group-1-value"></span>
    <br><br>
    Your favorite parks in San Francisco are: <span id="multiple-group-2-value"></span>
</p>
<sp-popover open style="position: relative">
    <sp-menu
        label="What are your favorite parks?"
        style="width: 200px"
        onchange="this.parentElement
                    .previousElementSibling
                    .querySelector(`#${arguments[0].target.id}-value`)
                    .textContent = arguments[0].target.value.replace(/,/g,', ')">
        <sp-menu-group
            id="multiple-group-1"
            selects="multiple"
        >
            <span slot="header">New York</span>
            <sp-menu-item>
                Central Park
            </sp-menu-item>
            <sp-menu-item>
                Flushing Meadows Corona Park
            </sp-menu-item>
            <sp-menu-item>
                Prospect Park
            </sp-menu-item>
        </sp-menu-group>
        <sp-menu-group
            id="multiple-group-2"
            selects="multiple"
        >
            <span slot="header">San Francisco</span>
            <sp-menu-item>
                Golden Gate Park
            </sp-menu-item>
            <sp-menu-item>
                John McLaren Park
            </sp-menu-item>
            <sp-menu-item>
                Lake Merced Park
            </sp-menu-item>
        </sp-menu-group>
    </sp-menu>
</sp-popover>
 Inherit 
<p>
    Your favorite park is: <span id="inherit-group-value"></span>
</p>
<sp-popover open style="position: relative">
    <sp-menu
        id="inherit-group"
        label="What are your favorite parks?"
        style="width: 200px"
        selects="single"
        onchange="this.parentElement
                    .previousElementSibling
                    .querySelector(`#${arguments[0].target.id}-value`)
                    .textContent = arguments[0].target.value">
        <sp-menu-group
            id="inherit-group-1"
            selects="inherit"
        >
            <span slot="header">New York</span>
            <sp-menu-item>
                Central Park
            </sp-menu-item>
            <sp-menu-item>
                Flushing Meadows Corona Park
            </sp-menu-item>
            <sp-menu-item>
                Prospect Park
            </sp-menu-item>
        </sp-menu-group>
        <sp-menu-group
            id="inherit-group-2"
            selects="inherit"
        >
            <span slot="header">San Francisco</span>
            <sp-menu-item>
                Golden Gate Park
            </sp-menu-item>
            <sp-menu-item>
                John McLaren Park
            </sp-menu-item>
            <sp-menu-item>
                Lake Merced Park
            </sp-menu-item>
        </sp-menu-group>
    </sp-menu>
</sp-popover>

Accessibility

Review the accessibility guidelines for the menu-item children and the guidelines for the parent menu.

Attributes and Properties

Property Attribute Type Default Description ignore ignore boolean false label label string '' selects selects undefined | 'inherit' | 'single' | 'multiple' whether the element has a specific selection algorithm that it applies to its item descendants. `single` allows only one descendent to be selected at a time. `multiple` allows many descendants to be selected. `inherit` will be applied dynamically when an ancestor of this element is actively managing the selection of its descendents. When the `selects` attribute is not present a `value` will not be maintained and the Menu Item children of this Menu will not have their `selected` state managed. value value string '' valueSeparator value-separator string ','

Slots

Name Description header headline of the menu group default slot menu items to be listed in the group

Events

Name Type Description change Event Announces that the `value` of the element has changed close Event