Vertical Navigation

lightning:verticalNavigation

Represents a vertical list of links that either take the user to another page or parts of the page the user is in. This component requires API version 41.0 and later.

For Aura components only. For LWC development, use lightning-vertical-navigation.

For Use In

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

A lightning:verticalNavigation component represents a list of links that’s only one level deep, with support for overflow sections that collapse and expand. The overflow section must be created using lightning:verticalNavigationOverflow and does not adjust automatically based on the view port.

This component implements styling from vertical navigation in the Lightning Design System.

lightning:verticalNavigation is used together with these sub-components.

lightning:verticalNavigationSection
lightning:verticalNavigationItem
lightning:verticalNavigationOverflow
lightning:verticalNavigationItemBadge
lightning:verticalNavigationItemIcon

This example creates a basic vertical navigation menu.

1<aura:component>
2  <lightning:verticalNavigation>
3    <lightning:verticalNavigationSection label="Reports">
4      <lightning:verticalNavigationItem label="Recent" name="recent" />
5      <lightning:verticalNavigationItem label="Created by Me" name="created" />
6      <lightning:verticalNavigationItem
7        label="Private Reports"
8        name="private"
9      />
10      <lightning:verticalNavigationItem label="Public Reports" name="public" />
11      <lightning:verticalNavigationItem label="All Reports" name="all" />
12    </lightning:verticalNavigationSection>
13  </lightning:verticalNavigation>
14</aura:component>

To define an active navigation item, use selectedItem="itemName" on lightning:verticalNavigation, where itemName matches the name of the lightning:verticalNavigationItem component to be highlighted.

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

1<aura:component>
2  <lightning:verticalNavigation selectedItem="recent">
3    <lightning:verticalNavigationSection label="Reports">
4      <lightning:verticalNavigationItem label="Recent" name="recent" />
5      <lightning:verticalNavigationItem label="All Reports" name="all" />
6    </lightning:verticalNavigationSection>
7    <lightning:verticalNavigationOverflow>
8      <lightning:verticalNavigationItem
9        label="Regional Sales East"
10        name="east"
11      />
12      <lightning:verticalNavigationItem
13        label="Regional Sales West"
14        name="west"
15      />
16    </lightning:verticalNavigationOverflow>
17  </lightning:verticalNavigation>
18</aura:component>

To create a navigation menu via JavaScript, pass in a map of key-value pairs that define the sub-components. Here’s an example that creates a navigation menu during component initialization.

1<aura:component>
2  <aura:attribute
3    name="navigationData"
4    type="Object"
5    description="The list of sections and their items."
6  />
7  <aura:handler name="init" value="{! this }" action="{! c.init }" />
8  <lightning:verticalNavigation>
9    <aura:iteration items="{! v.navigationData }" var="section">
10      <lightning:verticalNavigationSection label="{! section.label }">
11        <aura:iteration items="{! section.items }" var="item">
12          <aura:if isTrue="{! !empty(item.icon) }">
13            <lightning:verticalNavigationItemIcon
14              label="{! item.label }"
15              name="{! item.name }"
16              iconName="{! item.icon }"
17            />
18            <aura:set attribute="else">
19              <lightning:verticalNavigationItem
20                label="{! item.label }"
21                name="{! item.name }"
22              />
23            </aura:set>
24          </aura:if>
25        </aura:iteration>
26      </lightning:verticalNavigationSection>
27    </aura:iteration>
28  </lightning:verticalNavigation>
29</aura:component>

The client-side controller creates two sections with two navigation items each.

1({
2  init: function (component) {
3    var sections = [
4      {
5        label: "Reports",
6        items: [
7          {
8            label: "Created by Me",
9            name: "default_created",
10          },
11          {
12            label: "Public Reports",
13            name: "default_public",
14          },
15        ],
16      },
17      {
18        label: "Dashboards",
19        items: [
20          {
21            label: "Favorites",
22            name: "default_favorites",
23            icon: "utility:favorite",
24          },
25          {
26            label: "Most Popular",
27            name: "custom_mostpopular",
28          },
29        ],
30      },
31    ];
32    component.set("v.navigationData", sections);
33  },
34});

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

1.THIS {
2    width: 320px;
3}

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.

Attributes

Name	Description	Type	Default
ariaLabel	The aria label attribute for the navigation component	String
body	The body of the component. In markup, this is everything in the body of the tag.	Aura.Component[]
class	A CSS class for the outer element, in addition to the component's base classes.	String
compact	Specify true to reduce spacing between navigation items. This value defaults to false.	Boolean	false
onbeforeselect	Action fired before an item is selected. The event params include the `name` of the selected item. To prevent the onselect handler from running, call event.preventDefault() in the onbeforeselect handler.	Aura.Action
onselect	Action fired when an item is selected. The event params include the `name` of the selected item.	Aura.Action
selectedItem	Name of the nagivation item to make active.	String
shaded	Specify true when the vertical navigation is sitting on top of a shaded background. This value defaults to false.	Boolean	false
title	Displays tooltip text when the mouse moves over the element.	String

Dynamically Creating a Navigation Menu

Usage Considerations

Accessibility

Attributes

Lightning Component Reference

Contents