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.

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

<aura:component>
    <lightning:verticalNavigation>
            <lightning:verticalNavigationSection label="Reports">
                <lightning:verticalNavigationItem label="Recent" name="recent" />
                <lightning:verticalNavigationItem label="Created by Me" name="created" />
                <lightning:verticalNavigationItem label="Private Reports" name="private" />
                <lightning:verticalNavigationItem label="Public Reports" name="public" />
                <lightning:verticalNavigationItem label="All Reports" name="all" />
            </lightning:verticalNavigationSection>
        </lightning:verticalNavigation>
</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.

<aura:component>
    <lightning:verticalNavigation selectedItem="recent">
        <lightning:verticalNavigationSection label="Reports">
            <lightning:verticalNavigationItem label="Recent" name="recent" />
            <lightning:verticalNavigationItem label="All Reports" name="all" />
        </lightning:verticalNavigationSection>
        <lightning:verticalNavigationOverflow>
            <lightning:verticalNavigationItem label="Regional Sales East" name="east" />
            <lightning:verticalNavigationItem label="Regional Sales West" name="west" />
        </lightning:verticalNavigationOverflow>
    </lightning:verticalNavigation>
</aura:component>
Dynamically Creating a Navigation Menu

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.

<aura:component>
    <aura:attribute name="navigationData" type="Object" description="The list of sections and their items." />
    <aura:handler name="init" value="{! this }" action="{! c.init }" />
    <lightning:verticalNavigation>
            <aura:iteration items="{! v.navigationData }" var="section">
                <lightning:verticalNavigationSection label="{! section.label }">
                    <aura:iteration items="{! section.items }" var="item">
                        <aura:if isTrue="{! !empty(item.icon) }">
                            <lightning:verticalNavigationItemIcon
                                label="{! item.label }"
                                name="{! item.name }"
                                iconName="{! item.icon }" />
                            <aura:set attribute="else">
                                <lightning:verticalNavigationItem
                                    label="{! item.label }"
                                    name="{! item.name }" />
                            </aura:set>
                        </aura:if>
                    </aura:iteration>
                </lightning:verticalNavigationSection>
            </aura:iteration>
        </lightning:verticalNavigation> 
</aura:component>

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

({
    init: function (component) {
        var sections = [
          {
            label: "Reports",
            items: [
              {
                label: "Created by Me",
                name: "default_created"
              },
              {
                label: "Public Reports",
                name: "default_public"
              }
            ]
          },
          {
            label: "Dashboards",
            items: [
              {
                label: "Favorites",
                name: "default_favorites",
                icon: "utility:favorite"
              },
              {
                label: "Most Popular",
                name: "custom_mostpopular"
              }
            ]
          }
        ];
        component.set('v.navigationData', sections);
    }
})
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.

.THIS {
    width: 320px;
}
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

Attribute Name Attribute Type Description Required?
body Component[] The body of the component. In markup, this is everything in the body of the tag.
ariaLabel String The aria-label attribute for the navigation component.
class String A CSS class for the outer element, in addition to the component's base classes.
compact Boolean Specify true to reduce spacing between navigation items. This value defaults to false.
onbeforeselect Action 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.
onselect Action Action fired when an item is selected. The event params include the `name` of the selected item.
selectedItem String Name of the nagivation item to make active.
shaded Boolean Specify true when the vertical navigation is sitting on top of a shaded background. This value defaults to false.
title String Displays tooltip text when the mouse moves over the element.