Basic Navigation

In Lightning Experience and the Salesforce mobile app, each page corresponds to a PageReference JavaScript object. A PageReference is a JavaScript object that describes the page type, its attributes, and the state of the page. Using a PageReference insulates your component from future changes to URL formats. It also allows your component to be used in multiple applications, each of which can use different URL formats.

Use the following resources to simplify navigation across your apps. URLs for components using these resources are case-sensitive.

The lightning/navigation module

Use the navigation service, lightning/navigation, to navigate to many different page types, like records, list views, and objects. Also use the navigation service to open files.

The lightning__UrlAddressable target

To generate a URL for a component so you can navigate directly to it, add the lightning__UrlAddressable target to the component's .js-meta.xml configuration file. You can navigate to the component using lightning/navigation with the standard__component page reference type.

PageReference supports the following properties.

PageReference PropertyTypeDescriptionRequired
typeStringTo navigate in Lightning Experience, Experience Builder sites, or the Salesforce mobile app, define a PageReference object. The PageReference type generates a unique URL format and defines attributes that apply to all pages of that type. For Experience Builder sites, depending on the page type, the PageReference property requirements can differ between LWR sites and Aura sites. See PageReference Types.Yes
attributesObjectMap of name-value pairs that determine the target page. The page type defines the set of possible attribute names and their respective value types.Yes
stateObjectSet of key-value pairs with string keys and string values. These parameters conditionally customize content within a given page. Some page reference types support a standard set of state properties. You can also pass non-standard properties into state as long as they are namespaced.No

The navigation service adds two APIs to your component's class. Since these APIs are methods on the class, invoke them from this.

  • [NavigationMixin.Navigate](pageReference, [replace])

    A component calls this[NavigationMixin.Navigate] to navigate to another page in the application.

  • [NavigationMixin.GenerateUrl](pageReference)

    A component calls this[NavigationMixin.GenerateUrl] to get a promise that resolves to the resulting URL. The component can use the URL in the href attribute of an anchor. It can also use the URL to open a new window using the window.open({url}) browser API.

  1. In the component’s JavaScript class, import the NavigationMixin function from the lightning/navigation module.

  2. Apply the NavigationMixin function to your component’s base class.

  3. Create a plain JavaScript PageReference object that defines the page.

  4. To dispatch the navigation request, call the navigation service’s [NavigationMixin.Navigate](pageReference, [replace]) function. If replace is set to true, the pageReference replaces the existing entry in the browser history so the user doesn’t have to press the back button twice. The default value is false.

This example shows a link to the account home page. When a user clicks the link, the click event handler, handleClick, calls the navigation service’s Navigate method, which loads the account home page. The account home URL is also available in the anchor tag, which allows users to copy the link or open it in a new window.

In the component’s JavaScript file, import the navigation service.

To navigate to the account home page and to generate its URL, the navigation service uses a PageReference object. The PageReference object, accountHomePageRef, is defined in the connectedCallback() lifecycle hook when the component is inserted into the DOM. The navigation service stores the account home URL in the url property, which is used in the template.

The handleClick event handler is also defined in the component’s JavaScript class, and navigates to the page reference, accountHomePageRef.

The lwc-recipes repo has navigation service examples. Look for components that start with navTo, such as navToHome.

See Also