Note: This release is in preview. Features described here don’t become generally available until the latest general availability date that Salesforce announces for this release. Before then, and where features are noted as beta, pilot, or developer preview, we can’t guarantee general availability within any particular time frame or at all. Make your purchase decisions only on the basis of generally available products and features.

setSelectedNavigationItem() for Lightning Experience

Sets the selected navigation item to a specific ID. This method works only in Lightning console apps.

Arguments

The method provides the same argument for both Aura Components and Lightning Web Components (LWC).

Name	Type	Description
developerName	string	The API name of the navigation item to select. Examples include `'standard-Account'`, `'standard-Contact'`, and `'MyCustomObject__c'`

LWC Sample Code

This example switches the active navigation item to a different item in a Lightning console app.

1import { LightningElement } from 'lwc';
2import { setSelectedNavigationItem } from 'lightning/platformNavigationItemApi';
3
4export default class MyComponent extends LightningElement {
5    async navigateToAccounts() {
6        try {
7            await setSelectedNavigationItem('standard-Account');
8            console.log('Switched to Accounts navigation item');
9        } catch (error) {
10            console.error('Failed to select navigation item:', error);
11        }
12    }
13
14    async navigateToCustomObject() {
15        try {
16            await setSelectedNavigationItem('MyCustomObject__c');
17            console.log('Switched to custom object navigation item');
18        } catch (error) {
19            console.error('Navigation item not found:', error);
20        }
21    }
22}

This example finds a navigation item by label using both getNavigationItems() and setSelectedNavigationItem().

1import { LightningElement } from 'lwc';
2import { getNavigationItems, setSelectedNavigationItem } from 'lightning/platformNavigationItemApi';
3
4export default class MyComponent extends LightningElement {
5    async selectNavigationByLabel(targetLabel) {
6        try {
7            const items = await getNavigationItems();
8            const targetItem = items.find(item => item.label === targetLabel);
9
10            if (targetItem) {
11                await setSelectedNavigationItem(targetItem.developerName);
12                console.log(`Navigated to ${targetLabel}`);
13            } else {
14                console.error(`Navigation item "${targetLabel}" not found`);
15            }
16        } catch (error) {
17            console.error('Navigation failed:', error);
18        }
19    }
20}

Aura Components Sample Code

This Aura component has a button that, when pressed, sets the specified ID as the selected navigation item.

Component code:

1<aura:component implements="flexipage:availableForAllPageTypes" description="My Lightning Component">
2    <lightning:navigationItemAPI aura:id="navigationItemAPI" />
3    <lightning:button label="Set Navigation Item" onclick="{! c.setSelectedNavigationItem }" />
4</aura:component>

Controller code:

1({
2    setSelectedNavigationItem : function(component, event, helper) {
3        var navigationItemAPI = component.find("navigationItemAPI");
4        navigationItemAPI.setSelectedNavigationItem({
5            "developerName": "standard-Account"
6       }).then(function(response) {
7            console.log(response);
8        })
9        .catch(function(error) {
10            console.log(error);
11        });
12    }
13})

Response

This method returns a promise that, upon success, resolves to true.

Salesforce Console Developer Guide

setSelectedNavigationItem() for Lightning Experience

Arguments

LWC Sample Code

Aura Components Sample Code

Response