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-sectionlightning-vertical-navigation-itemlightning-vertical-navigation-overflowlightning-vertical-navigation-item-badgelightning-vertical-navigation-item-icon This example creates a basic vertical navigation menu.
1 <lightning-vertical-navigation> 2 <lightning-vertical-navigation-section label = "Reports" > 3 <lightning-vertical-navigation-item 4 label = "Recent" 5 name = "recent" 6 ></lightning-vertical-navigation-item> 7 <lightning-vertical-navigation-item 8 label = "Created by Me" 9 name = "created" 10 ></lightning-vertical-navigation-item> 11 <lightning-vertical-navigation-item 12 label = "Private Reports" 13 name = "private" 14 ></lightning-vertical-navigation-item> 15 <lightning-vertical-navigation-item 16 label = "Public Reports" 17 name = "public" 18 ></lightning-vertical-navigation-item> 19 <lightning-vertical-navigation-item 20 label = "All Reports" 21 name = "all" 22 ></lightning-vertical-navigation-item> 23 </lightning-vertical-navigation-section> 24 </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.
1 <lightning-vertical-navigation selected-item = "recent" > 2 <lightning-vertical-navigation-section label = "Reports" > 3 <lightning-vertical-navigation-item 4 label = "Recent" 5 name = "recent" 6 ></lightning-vertical-navigation-item> 7 <lightning-vertical-navigation-item 8 label = "All Reports" 9 name = "all" 10 ></lightning-vertical-navigation-item> 11 </lightning-vertical-navigation-section> 12 <lightning-vertical-navigation-overflow> 13 <lightning-vertical-navigation-item 14 label = "Regional Sales East" 15 name = "east" 16 ></lightning-vertical-navigation-item> 17 <lightning-vertical-navigation-item 18 label = "Regional Sales West" 19 name = "west" 20 ></lightning-vertical-navigation-item> 21 </lightning-vertical-navigation-overflow> 22 </lightning-vertical-navigation> Select a Navigation Item
To determine which navigation item is selected, use the event.detail property on the onselect event handler.
1 <lightning-vertical-navigation onselect = { handleSelect } selected-item = "recent" > 2 <lightning-vertical-navigation-section label = "Reports" > 3 <lightning-vertical-navigation-item 4 label = "Recent" 5 name = "recent" 6 ></lightning-vertical-navigation-item> 7 <lightning-vertical-navigation-item 8 label = "Created by Me" 9 name = "created" 10 ></lightning-vertical-navigation-item> 11 <lightning-vertical-navigation-item 12 label = "All Reports" 13 name = "all" 14 ></lightning-vertical-navigation-item> 15 </lightning-vertical-navigation-section> 16 </lightning-vertical-navigation> The onselect event handler returns the name of the navigation item that’s selected.
1 import { LightningElement } from "lwc" ; 2 3 export default class VerticalNavigationExample extends LightningElement { 4 handleSelect ( event ) { 5 const selectedName = event . detail . name ; 6 } 7 } 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.
1 <div style = "width: 320px;" > 2 <lightning-vertical-navigation> ... </lightning-vertical-navigation> 3 </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.
Parameter Type Description name string The name of the item to be selected, which matches the name value on the vertical-navigation-item component.
The event properties are as follows.
Property Value Description bubbles false This event does not bubble. cancelable true This event can be canceled. You can call preventDefault() on this event. composed false This event does not propagate outside the template in which it was dispatched.
select
The event fired when a navigation item is selected.
The select event returns the following parameter.
Parameter Type Description name string The name of the selected item, which matches the name value on the vertical-navigation-item component.
The event properties are as follows.
Property Value Description bubbles false This event does not bubble. cancelable false This event has no default behavior that can be canceled. You can’t call preventDefault() on this event. composed false This event does not propagate outside the template in which it was dispatched.
