Lightning Console JavaScript API Syntax

LWC Syntax

To use LWC Workspace API, import lightning/platformWorkspaceApi in your JavaScript code.

The lightning/platformWorkspaceApi module gives you access to workspace API methods, wire adapters, and Lightning message channels. Access Lightning message channels by importing from @salesforce/messageChannel/lightning__tab*. For example, @salesforce/messageChannel/lightning__tabClosed.

The following example shows a Lightning web component that uses the openSubtab API method and EnclosingTabId wire adapter.

1import { LightningElement, wire } from 'lwc';
2import { EnclosingTabId, openSubtab } from 'lightning/platformWorkspaceApi';
3
4export default class MyComponent extends LightningElement {
5  @wire(EnclosingTabId) tabId;
6
7  handleClick() {
8    if (!this.tabId) {
9      return;
10    }
11    // Open a record as a subtab of the current tab
12    openSubtab(this.tabId, { recordId: 'YourRecordId', focus: true });
13  }
14}

Configure the component’s .js-meta.xml file so the component can be accessed in the Lightning App Builder.

1<?xml version="1.0" encoding="UTF-8"?>
2<LightningComponentBundle xmlns="http://soap.sforce.com/2006/04/metadata">
3  <apiVersion>59.0</apiVersion>
4  <isExposed>true</isExposed>
5  <targets>
6      <target>lightning__RecordPage</target>
7      <target>lightning__AppPage</target>
8      <target>lightning__HomePage</target>
9  </targets>
10</LightningComponentBundle>

LWC supports Workspace API methods only. Similar to the Aura counterpart, methods in the Workspace API take a JSON object as an argument. The values included in the object depend on the method. For example, openTab takes an object that includes the url and focus (whether the new tab has focus). Check the reference section of this guide before using a method so that you know which arguments to pass to it.

Aura Components Syntax

To use the Lightning Console JavaScript API, include lightning:navigationItemAPI, lightning:workspaceAPI, or lightning:utilityBarAPI in your Aura component.

The lightning:navigationItemAPI, lightning:workspaceAPI, and lightning:utilityBarAPI components give you access to their coordinating APIs. Give each component an aura:id so that you can reference it from the component’s controller.

The following example shows a simple Aura component that uses the API libraries:

1<aura:component implements="flexipage:availableForAllPageTypes" access="global">
2    <lightning:navigationItemAPI aura:id="navigationItem" />
3    <lightning:workspaceAPI aura:id="workspace" />
4    <lightning:utilityBarAPI aura:id="utilityBar" />
5    <lightning:button label="Focus Navigation Item" onclick="{!c.focusNavigationItem }" />
6    <lightning:button label="Open Utility" onclick="{!c.openUtilityBar }"/>
7    <lightning:button label="Open Tab" onclick="{!c.openTab }" />
8</aura:component>

This component implements flexipage:availableForAllPageTypes so that it can be accessed in the Lightning App Builder.

The component’s JavaScript controller looks like this.

1({
2    openUtilityBar : function(component, event, helper) {
3        var utilityAPI = component.find("utilitybar");
4        utilityAPI.openUtility();
5    },
6
7    openTab: function(component, event, helper) {
8        var workspaceAPI = component.find("workspace");
9        workspaceAPI.openTab({
10            pageReference: {
11                "type": "standard__recordPage",
12                "attributes": {
13                    "recordId":"500xx000000Ykt2AAC",
14                    "actionName":"view"
15                },
16                "state": {}
17            },
18            focus: true
19        }).then(function(response) {
20            workspaceAPI.getTabInfo({
21            tabId: response
22        }).then(function(tabInfo) {
23            console.log("The recordId for this tab is: " + tabInfo.recordId);
24        });
25        }).catch(function(error) {
26            console.log(error);
27        });
28    },
29
30    focusNavigationItem : function(component, event, helper) {
31        var navigationItemAPI = component.find("navigationItem");
32        navigationItemAPI.focusNavigationItem().then(function(response) {
33            console.log(response);
34        })
35        .catch(function(error) {
36            console.log(error);
37        });
38    } 
39})

The controller has three functions, each of which uses an API method. To use a method in a controller, use component.find with the aura:id you gave to the lightning:navigationItemAPI, lightning:workspaceAPI, or lightning:utilityBarAPI.

Methods in the Workspace API and the Utility Bar API take a JSON object as an argument. The values included in the object depend on the method. openTab, for example, takes an object that includes the url and focus (whether the new tab has focus). Check the reference section of this guide before using a method so that you know which arguments to pass to it.

LWC VS Aura Guidelines

When working with the Lightning Console JavaScript API, consider these guidelines.

• In LWC, required parameters are explicitly passed to the method like focusTab(tabId);. In Aura, required parameters are passed to the method in an object like workspaceAPI.focusTab({tabId : response});.
• In LWC, pass in a URL that matches a Lightning Experience page, for example, /lightning/r/Account/001R0000003HgssIAC/view