Navigation | Legacy Components | Lightning Component Reference

lightning:navigation

Generates URL for a given pageReference. This component requires API version 43.0 and later.

For Aura components only. For LWC development, use lightning/navigation.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Mobile Offline

Use lightning:navigation component to navigate to a given pageReference or to generate a URL from a pageReference.

The following example generates a URL to an Account Object home based on its pageReference and sets the URL on an <a> element. The example assumes that you’re creating the component for a custom Lightning Component tab or a Lightning page by implementing force:appHostable and flexipage:availableForAllPageTypes.

1<aura:component implements="force:appHostable,flexipage:availableForAllPageTypes">
2  <aura:attribute name="url" type="String" />
3  <aura:attribute name="pageReference" type="Object" />
4  <aura:handler name="init" value="{! this }" action="{! c.init }" />
5  <lightning:navigation aura:id="navService" />
6  <a href="{!v.url}">Link</a>
7</aura:component>

In your client-side controller, set the pageReference attribute for the Account home page. Set the URL on your link using the generateUrl() method, which is useful for opening links in a new tab. Depending on whether you’re using the new URL format available as part of the Summer ’18 critical update, you might see a URL that begins with the new format /lightning/cmp/ or the old format one/one.app#/cmp/.

1({
2  init: function (cmp, event, helper) {
3    var navService = cmp.find("navService");
4    // Sets the route to /lightning/o/Account/home
5    var pageReference = {
6      type: "standard__objectPage",
7      attributes: {
8        objectApiName: "Account",
9        actionName: "home",
10      },
11    };
12    cmp.set("v.pageReference", pageReference);
13    // Set the URL on the link or use the default if there's an error
14    var defaultUrl = "#";
15    navService.generateUrl(pageReference).then(
16      $A.getCallback(function (url) {
17        cmp.set("v.url", url ? url : defaultUrl);
18      }),
19      $A.getCallback(function (error) {
20        cmp.set("v.url", defaultUrl);
21      }),
22    );
23  },
24});

You can also navigate directly to a page using a onclick handler.

1<lightning:navigation aura:id="navService" />
2<a href="{!v.url}" onclick="{!c.handleClick}">Link</a>
3<lightning:button label="Navigate" onclick="{!c.handleClick}" />

In your client-side controller, use the navigate() method to navigate to the page.

1({
2  handleClick: function (cmp, event, helper) {
3    var navService = cmp.find("navService");
4    // Uses the pageReference definition in the init handler
5    var pageReference = cmp.get("v.pageReference");
6    event.preventDefault();
7    navService.navigate(pageReference);
8  },
9});

Working with the PageReference Object

PageReference is a reference to a page, providing a well-defined structure that describes the page type and its corresponding values. You should use the PageReference definitions instead of attempting to parse the URL directly. The following PageReference properties are supported.

Property	Type	Description
type	string	Required. The API name of the PageDefinition.
attributes	object	Required. Values for each attribute specified by the PageDefinition.
state	object	Additional parameters, such as `filterName`, which is tied to the query string of the URL in Lightning Experience. The routing framework doesn’t depend on `state` to render a page.

For example, to set the route to /lightning/o/Account/list?filterName=MyAccounts:

1var pageReference = {
2  type: "standard__objectPage",
3  attributes: {
4    objectApiName: "Account",
5    actionName: "list",
6  },
7  state: {
8    filterName: "MyAccounts",
9  },
10};

For more information on the PageReference object, see the Lightning Aura Components Developer Guide.

Attributes

Name	Description	Type	Default	Required
body	The body of the component. In markup, this is everything in the body of the tag.	Aura.Component[]

Methods

Name	Description	Argument Name	Argument Type	Argument Description
generateUrl	Generates a URL for a given pageReference. Returns a Promise javascript object that resolves to a URL.	pageReference	Object	Defines the page reference. Required properties include 'type' and 'attributes'. 'state' is optional.
navigate	Requests navigation to the specified page reference.	pageReference	Object	Defines the page reference. Required properties include 'type' and 'attributes'. 'state' is optional.
navigate	Requests navigation to the specified page reference.	replace	Boolean	Indicates that the new page should replace the current page in the navigation history.