Vertical Navigation

lightning-vertical-navigation

A vertical list of links that either take the user to another page or parts of the page the user is in.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="verticalNavigation" model="lwc" namespace="lightning"}

:::::

:::::tab

A lightning-vertical-navigation component represents a list of links that's only one level deep, with support for overflow sections that collapse and expand.

To create an overflow section, use lightning-vertical-navigation-overflow. The overflow section doesn't adjust automatically based on the view port.

Design

lightning-vertical-navigation implements the vertical navigation blueprint in the Salesforce Lightning Design System (SLDS). The vertical navigation adapts to SLDS 1 or SLDS 2 styling based on the org's theme or the container app that you use.

Usage

Use lightning-vertical-navigation together with these sub-components.

• lightning-vertical-navigation-section
• lightning-vertical-navigation-item
• lightning-vertical-navigation-overflow
• lightning-vertical-navigation-item-badge
• lightning-vertical-navigation-item-icon

This example creates a basic vertical navigation menu.

<lightning-vertical-navigation>
    <lightning-vertical-navigation-section label="Reports">
        <lightning-vertical-navigation-item
            label="Recent"
            name="recent"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Created by Me"
            name="created"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Private Reports"
            name="private"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Public Reports"
            name="public"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="All Reports"
            name="all"
        ></lightning-vertical-navigation-item>
    </lightning-vertical-navigation-section>
</lightning-vertical-navigation>

To define an active navigation item, use selected-item="itemName" on lightning-vertical-navigation, where itemName matches the name of the lightning-vertical-navigation-item component to be highlighted.

This example creates a navigation menu with a highlighted item and an overflow section.

<lightning-vertical-navigation selected-item="recent">
    <lightning-vertical-navigation-section label="Reports">
        <lightning-vertical-navigation-item
            label="Recent"
            name="recent"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="All Reports"
            name="all"
        ></lightning-vertical-navigation-item>
    </lightning-vertical-navigation-section>
    <lightning-vertical-navigation-overflow>
        <lightning-vertical-navigation-item
            label="Regional Sales East"
            name="east"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Regional Sales West"
            name="west"
        ></lightning-vertical-navigation-item>
    </lightning-vertical-navigation-overflow>
</lightning-vertical-navigation>

Select a Navigation Item

To determine which navigation item is selected, use the event.detail property on the onselect event handler.

<lightning-vertical-navigation onselect={handleSelect} selected-item="recent">
    <lightning-vertical-navigation-section label="Reports">
        <lightning-vertical-navigation-item
            label="Recent"
            name="recent"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="Created by Me"
            name="created"
        ></lightning-vertical-navigation-item>
        <lightning-vertical-navigation-item
            label="All Reports"
            name="all"
        ></lightning-vertical-navigation-item>
    </lightning-vertical-navigation-section>
</lightning-vertical-navigation>

The onselect event handler returns the name of the navigation item that's selected.

import { LightningElement } from "lwc";

export default class VerticalNavigationExample extends LightningElement {
  handleSelect(event) {
    const selectedName = event.detail.name;
  }
}

Usage Considerations

If you want a navigation menu that's more than one level deep, consider using lightning-tree instead.

The navigation menu takes up the full width of the screen. You can specify a width by wrapping in a div and specifying width using CSS.

<div style="width: 320px;">
    <lightning-vertical-navigation> ... </lightning-vertical-navigation>
</div>

Accessibility

Use the Tab and Shift+Tab keys to navigate up and down the menu. To expand or collapse an overflow section, press the Enter key or Space Bar.

Custom Events

beforeselect

The event fired before a navigation item is selected.

The beforeselect event returns the following parameter.

The event properties are as follows.

select

The event fired when a navigation item is selected.

The select event returns the following parameter.

The event properties are as follows.

:::::

:::::tab ::component-specification{component="verticalNavigation" model="lwc" namespace="lightning"}

:::::

::::::