Side navigation allows users to locate information and features within the UI. It can be used for either hierarchical or flat navigation, and gives the ability to group navigable items categorically. Side navigation is an opportunity to prioritize content
npm install @spectrum-web-components/sidenavSide navigation allows users to locate information and features within the UI.
It can be used for either hierarchical or flat navigation, and gives the ability
to group navigable items categorically. Side navigation is an opportunity to
prioritize content or features based on your users’ needs in a way that
maintains clear, persistent visibility. Use side navigation within the context
of larger elements and mechanisms within the app frame.
View the design documentation for this component.
``bash`
yarn add @spectrum-web-components/sidenav
Import the side effectful registration of , , or via:
`js`
import '@spectrum-web-components/sidenav/sp-sidenav.js';
import '@spectrum-web-components/sidenav/sp-sidenav-heading.js';
import '@spectrum-web-components/sidenav/sp-sidenav-item.js';
When looking to leverage the Sidenav, SidenavHeading, or SidenavItem base classes as a type and/or for extension purposes, do so via:
`js`
import {
Sidenav,
SidenavHeading,
SidenavItem,
} from '@spectrum-web-components/sidenav';
The side navigation consists of several key parts:
- A container element that manages the side navigation behavior
- Individual side navigation items that may or may not be expandable
- Children side navigation items that are revealed when a parent item is expanded
- Optional heading with a label
`html live-demo`
Make sure to use the right option for the context and user needs. Don’t mix behavior, styles, or variations together in a single navigation menu. Follow these guidelines:
- When navigation is simple, use the single level side navigation.
- When navigation is simple but categorical, use the single level side navigation with headers.
- When navigation is expansive, hierarchical, and/or you need progressive disclosure in the menu behavior, use the multi-level side navigation. Up to three levels of navigation are supported.
`html`
href="/components/SideNav"
label="Docs"
selected
>
href="/guides"
label="Guides"
>
href="/community"
label="Community"
>
href="/storybook"
target="_blank"
label="Storybook"
>
href="/releases"
target="_blank"
label="Releases"
disabled
>
href="/github"
target="_blank"
label="Github"
>
In single-level side navigation, do not mix icon usage between side nav items. Either all side nav items have icons, or no items have icons. In cases where the navigation content might be user-generated, stick to text-only navigation items.
`html`
Use headings in single level side navigation when it's beneficial to group navigation items into categories. The headings are not interactive. If items don’t fall into a category, place them at the top. When using the heading variation, an entire category should either all have icons or all be text-only.
Although headings can be used in multi-level side navigation, they can only be used as first-level items, and are not to be nested.
`html`
Use variant="multilevel" when you have multiple layers of hierarchical navigation.
In the instances where a top-level navigation item has no children, clicking
will send the user to the location of the item. Additionally, headings can be used
in multi-level side navigation, but they can only be used as first-level items, and are not to be nested.
Up to three levels of navigation are supported.
`html`
label="Responsive"
>
label="Typography"
>
In multi-level side navigation, icon and text-only navigation items can be used in combination, but only the first-level items can have icons to maintain visual clarity and hierarchy. Icons only appear on first-level items, and sublevels (second and third) should not include icons. In cases where the navigation content might be user-generated, stick to text-only navigation items.
#### Multi-level side navigation icon usage
- All icons: all items have icons
- No icons: no items have icons
- Mixed icons: only first-level items have icons; second and third-level items do not
`html`
label="Typography"
>
label="Iconography"
>
When an side navigation item is programmatically selected in variant="multilevel", all of its parent items automatically expand to reveal the selection path.
When the manage-tab-index attribute is set on an element, it will present its children with a single tab-stop. This will leave items beyond the selected item (or when there is no focusable selected item), accessible via the up and down arrow keys. Items with expanded children that aren't selected lose focus when manage-tab-index is active.
#### Roles and ARIA attributes
- renders a