Navigation in Lightning Experience and the Salesforce Mobile App Using Page References

These navigation resources are supported only in Lightning Experience and the Salesforce mobile app. They’re not supported in other containers, such as Lightning Components for Visualforce, Lightning Out, or Communities. This is true even if you access these containers inside Lightning Experience or the Salesforce mobile app.

Use the following resources to simplify navigation across your apps. For examples, see the Component Library.

lightning:navigation

To navigate to a page or component, use the navigate() method in lightning:navigation. This approach is a substitute for a navigateTo* event, and both are supported.

To generate a URL in your component, use the generateUrl() method in lightning:navigation to resolve the URL.

generateUrl() returns a promise, which calls back with the resulting URL.

Note

lightning:isUrlAddressable

To enable a component to navigate directly via a URL, add the lightning:isUrlAddressable interface to your component.

pageReference and lightning:isUrlAddressable replace the force:navigateToComponent event for navigating directly to a component. Unlike the force:navigateToComponent event information mapping protocol, the only attribute populated through the navigation dispatching system is the pageReference attribute. Information is passed to the addressed component through the state properties on the target page reference. lightning:isUrlAddressable doesn’t automatically set attributes on the target component. Get parameters from v.pageReference.state and manually set them using the target component’s init handler.

Tip

pageReference provides a well-defined structure that describes the page type and its corresponding attributes. pageReference supports the following properties.

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

Because the key-value pairs of pageReference.state are serialized to URL query parameters, all its values are strings. Code that consumes values from the state must properly parse the value into the correct format. To delete a value from the state array, define it as undefined.

You can’t directly change the pageReference object. To update the state, create a new pageReference object, and copy the values using Object.assign().

state parameters must be namespaced. For example, a managed package with the namespace abc with a parameter accountId is represented as abc__accountId. The namespace for custom components is c__.Parameters without a namespace are reserved for Salesforce use. This namespace restriction is introduced under a CRUC in Winter ’18 and enforced in Spring ’19.

Migrate to lightning:isUrlAddressable from force:navigateToComponent

If you’re currently using the force:navigateToComponent event, you can provide backward compatibility for bookmarked links by redirecting requests to a component that uses lightning:isUrlAddressable.

First, copy your original component, including its definition, controller, helper, renderer, and CSS. Make the new component implement the lightning:isUrlAddressable interface.

Change the new component to read the values passed through the navigation request from cmp.get("v.pageReference").state.

1// Add a handler to your component 
2<aura:handler name="init" value="{!this}" action="{!c.init}" />
3
4// Controller example
5({
6    init: function(cmp, event, helper) {
7        var pageReference = cmp.get("v.pageReference");
8        cmp.set("v.myAttr", pageReference.state.c__myAttr);
9        // myAttr can be modified, but isn’t reflected in the URL 
10    }
11})

In the new component, remove the attributes mapped from the URL that aren’t used to copy values from the page state in the component’s init handler.

Change the instances that navigate to your old component to the new API and address of your new component. For example, remove instances of force:navigateToComponent, like $A.get("e.force:navigateToComponent").setParams({componentDef: "c:oldCmp", attributes: {"myAttr": "foo"}}).fire();.

1cmp.find("navigationService").navigate({
2    type: "standard__component",
3    attributes: {
4        name: "c:myCmpCopy" },
5    state: { "c__myAttr": "foo" }});

1({
2    init: function(cmp, event, helper) {
3        cmp.find("navigation").navigate({
4            type: "standard__component",
5            attributes: {
6                componentName: "c__componentB" },
7            state: {
8                c__myAttr: cmp.get("v.myAttr")
9            } 
10        }, true); // replace = true 
11    }
12})