sp-sidenav

Examples API

Attributes and Properties #

Property Attribute Type Default Description
manageTabIndex manage-tab-index boolean false
value value string | undefined undefined

Slots #

Name Description
default slot the Sidenav Items to display

Events #

Name Type Description
change Event Announces a change in the `value` property of the navigation element. This change can be "canceled" via `event.preventDefault()`.

CSS Custom Properties #

Name Default
--spectrum-sidenav-heading-border-radius var(--spectrum-alias-border-radius-regular)
--spectrum-sidenav-heading-gap-bottom var(--spectrum-global-dimension-size-50)
--spectrum-sidenav-heading-gap-top var(--spectrum-global-dimension-size-200)
--spectrum-sidenav-heading-height var(--spectrum-alias-single-line-height)
--spectrum-sidenav-heading-padding-x var(--spectrum-global-dimension-size-150)
--spectrum-sidenav-heading-text-color var(--spectrum-global-color-gray-700)
--spectrum-sidenav-heading-text-font-weight var(--spectrum-global-font-weight-medium)
--spectrum-sidenav-heading-text-letter-spacing var(--spectrum-global-font-letter-spacing-medium)
--spectrum-sidenav-heading-text-size var(--spectrum-global-dimension-font-size-50)
--spectrum-sidenav-icon-gap var(--spectrum-global-dimension-size-100)
--spectrum-sidenav-item-background-color var(--spectrum-alias-background-color-transparent)
--spectrum-sidenav-item-background-color-disabled var(--spectrum-alias-background-color-transparent)
--spectrum-sidenav-item-background-color-down var(--spectrum-alias-highlight-hover)
--spectrum-sidenav-item-background-color-hover var(--spectrum-alias-highlight-hover)
--spectrum-sidenav-item-background-color-key-focus var(--spectrum-alias-highlight-hover)
--spectrum-sidenav-item-background-color-selected var(--spectrum-alias-highlight-hover)
--spectrum-sidenav-item-border-color-key-focus var(--spectrum-alias-border-color-key-focus)
--spectrum-sidenav-item-border-radius var(--spectrum-alias-border-radius-regular)
--spectrum-sidenav-item-gap var(--spectrum-global-dimension-size-50)
--spectrum-sidenav-item-height var(--spectrum-alias-single-line-height)
--spectrum-sidenav-item-padding-x var(--spectrum-global-dimension-size-150)
--spectrum-sidenav-item-text-color var(--spectrum-alias-text-color)
--spectrum-sidenav-item-text-color-disabled var(--spectrum-alias-text-color-disabled)
--spectrum-sidenav-item-text-color-hover var(--spectrum-alias-text-color-hover)
--spectrum-sidenav-item-text-color-key-focus var(--spectrum-alias-text-color-hover)
--spectrum-sidenav-item-text-color-selected var(--spectrum-alias-text-color-hover)
--spectrum-sidenav-item-text-font-weight var(--spectrum-global-font-weight-regular)
--spectrum-sidenav-item-text-size var(--spectrum-alias-font-size-default)
--spectrum-sidenav-multilevel-item-margin-left var(--spectrum-global-dimension-size-150)
--spectrum-sidenav-multilevel-main-item-font-weight var(--spectrum-global-font-weight-bold)
--spectrum-tabs-m-focus-ring-size var(--spectrum-alias-border-size-thick)

Description #

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 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.

<sp-sidenav> elements accept both <sp-sidenav-item> and <sp-sidenav-heading> elements as children in order to construct a hierarchy of navigation elements. <sp-sidenav-item> elements will place themselves as a togglable child of their <sp-sidenav> element parent. <sp-sidenav-heading> elements will create visible structure by grouping their child <sp-sidenav-item> children under a non-interactive heading.

Usage #

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

yarn add @spectrum-web-components/sidenav

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

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:

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

Example #

<sp-sidenav defaultValue="Docs">
<sp-sidenav-item value="Docs" href="/components/SideNav">
Docs
</sp-sidenav-item>
<sp-sidenav-item value="Guides" href="/guides/getting_started">
Guides
</sp-sidenav-item>
<sp-sidenav-item value="Community" href="/community">
Community
</sp-sidenav-item>
<sp-sidenav-item value="Storybook" href="/storybook" target="_blank">
Storybook
</sp-sidenav-item>
<sp-sidenav-item
value="Releases"
href="http://git.corp.adobe.com/React/react-spectrum/releases"
target="_blank"
disabled
>

Releases
</sp-sidenav-item>
<sp-sidenav-item
value="GitHub"
href="http://git.corp.adobe.com/React/react-spectrum"
target="_blank"
>

GitHub
</sp-sidenav-item>
</sp-sidenav>

Multi-level #

Use this variation when you have multiple layers of hierarchical navigation. The headers are styled differently and possess the same interactive behavior as a treeview; clicking the header opens and collapses the children navigation items. In the instances where a top-level navigation item has no children, clicking will send the user to the location of the item.

<sp-sidenav variant="multilevel" defaultValue="Layout">
<sp-sidenav-item value="Guidelines" label="Guidelines"></sp-sidenav-item>
<sp-sidenav-item value="Styles" label="Styles" expanded>
<sp-sidenav-item value="Color" label="Color"></sp-sidenav-item>
<sp-sidenav-item value="Grid" label="Grid" expanded>
<sp-sidenav-item value="Layout" label="Layout"></sp-sidenav-item>
<sp-sidenav-item value="Responsive" label="Responsive"></sp-sidenav-item>
</sp-sidenav-item>
<sp-sidenav-item value="Typography" label="Typography"></sp-sidenav-item>
</sp-sidenav-item>
<sp-sidenav-item value="Elements" label="Elements"></sp-sidenav-item>
<sp-sidenav-item value="Patterns" label="Patterns"></sp-sidenav-item>
</sp-sidenav-itm>

Icon #

<sp-sidenav>
<sp-sidenav-item value="Section Title 1" label="Section Title 1">
<sp-icon-star slot="icon"></sp-icon-star>
</sp-sidenav-item>
<sp-sidenav-item value="Section Title 2" label="Section Title 2">
<sp-icon-star slot="icon"></sp-icon-star>
</sp-sidenav-item>
<sp-sidenav-item value="Section Title 3" label="Section Title 3">
<sp-icon-star slot="icon"></sp-icon-star>
</sp-sidenav-item>
</sp-sidenav>

Heading #

<sp-sidenav variant="multilevel">
<sp-sidenav-item value="Section 1" label="Section 1"></sp-sidenav-item>
<sp-sidenav-item value="Section 2" label="Section 2"></sp-sidenav-item>
<sp-sidenav-heading label="Category 1">
<sp-sidenav-item value="Section 3" label="Section 3"></sp-sidenav-item>
<sp-sidenav-item value="Section 4" label="Section 4"></sp-sidenav-item>
</sp-sidenav-heading>
<sp-sidenav-heading label="Category 2">
<sp-sidenav-item value="Section 5" label="Section 5"></sp-sidenav-item>
<sp-sidenav-item value="Section 6" label="Section 6"></sp-sidenav-item>
</sp-sidenav-heading>
</sp-sidenav>

Accessibility #

When the manage-tab-index attribute is set on an sp-sidenav element then it will presents its child sp-sidenav-item children with a single tab-stop. This will leave items beyond the selected item, or first when there is no focusable selected item, will be accessibile via the up and down arrow keys.