sp-sidenav-heading

NPM 1.7.0

View Storybook

Try it on Stackblitz
Overview API

Overview

<sp-sidenav-heading> elements will create visible structure by grouping their child <sp-sidenav-item> children under a non-interactive heading. Headings are used at the first level of navigation, and should not be used in any subsequent navigation level.

Usage

See it on NPM! How big is this package in your project?

yarn add @spectrum-web-components/sidenav

Import the side effectful registration of <sp-sidenav-heading> via:

import '@spectrum-web-components/sidenav/sp-sidenav-heading.js';

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

import { SidenavHeading } from '@spectrum-web-components/sidenav';

Anatomy

  • Label: text content of the heading
  • Default slot: children <sp-sidenav-item> elements will be categorized under the heading element

Options

Single-level with headings

Use a single level side navigation with headings when needing to group navigation items into categories. Headings are not interactive.

<sp-sidenav>
    <sp-sidenav-heading label="Docs heading">
        <sp-sidenav-item
            value="new-docs"
            label="New docs"
            href="/components/sidenav"
        ></sp-sidenav-item>
        <sp-sidenav-item
            value="old-docs"
            label="Old docs"
            href="/components/sidenav"
        ></sp-sidenav-item>
    </sp-sidenav-heading>
</sp-sidenav>
 Multi-level with headings

In multi-level side navigation, headings can only be used at the first level of navigation. Do not nest headings within second or third level side nav items.

<sp-sidenav variant="multilevel">
    <sp-sidenav-heading label="Styles">
        <sp-sidenav-item value="Color" label="Color"></sp-sidenav-item>
        <sp-sidenav-item value="Grid" label="Grid"></sp-sidenav-item>
        <sp-sidenav-heading label="Heading styles">
            <sp-sidenav-item value="Typography" label="Typography" expanded>
                <sp-sidenav-item
                    value="Display"
                    label="Display headings"
                ></sp-sidenav-item>
                <sp-sidenav-item value="H1" label="H1"></sp-sidenav-item>
                <sp-sidenav-item value="H2" label="H2"></sp-sidenav-item>
            </sp-sidenav-item>
        </sp-sidenav-heading>

        <sp-sidenav-heading label="Font styles">
            <sp-sidenav-item value="Body" label="Body copy"></sp-sidenav-item>
            <sp-sidenav-item value="Details" label="Details"></sp-sidenav-item>
            <sp-sidenav-item value="Code" label="Code"></sp-sidenav-item>
        </sp-sidenav-heading>
    </sp-sidenav-heading>
</sp-sidenav>

Accessibility

Although <sp-sidenav-heading> elements are non-interactive, they do offer accessibility features:

  • Uses <h2> elements for heading text to provide proper document outline
  • Automatically sets role="listitem" on the heading component itself
  • Creates a nested role="list" container for grouped navigation items
  • aria-labelledby is set to the id of rendered <h2> tag on nested list items to associate the list with the heading

Attributes and Properties

Property Attribute Type Default Description label label string ''

Slots

Name Description default slot the Sidenav Items to display in association with the heading