Add Query Parameters

To add query parameters to the URL, update the PageReference.state property. The navigation service uses a PageReference to generate a URL. The key-value pairs of the state property are serialized to URL query parameters. The query parameters describe the page and form a more specific URL that the user can save or bookmark.

Work With the state Property

Keep these behaviors in mind when working with the state property.

The PageReference object is frozen, so you can’t change it directly. To navigate to the same page with a modified state, copy the current PageReference and modify the copy using Object.assign({}, pageReference).
state properties must use a namespace prefix followed by two underscores, __. If the component isn’t part of a managed package, use c for the namespace prefix. If the component is part of a managed package, use the package’s namespace.
Since the key-value pairs of PageReference.state are serialized to URL query parameters, all the values must be strings.
Code that consumes a value from state must parse the value into its proper format.
To delete a value from the state object, set it as undefined.
Even when using HTTPS, including personal data for URL parameters isn’t safe. See Storing Sensitive Data for details.
In Lightning Experience and Experience Builder sites that are built with Aura or LWR templates, the view isn’t rerendered when only the URL query string changes. To react to a change in the URL query string, we recommend that components observe the CurrentPageReference object and compare against the page reference’s state.

Example: Update the Current Page State

The component in this example has a link labeled Show Panel that changes to Hide Panel when clicked. Clicking either link updates the current page’s state. When the page state changes, the this.currentPageReference property, decorated with @wire(CurrentPageReference), updates. The component rerenders to show or hide the panel and update the link label.

1<!-- pageStateChangeExample.html -->
2<template>
3  <div>
4    <a href={showPanelUrl} onclick={handleShowPanelClick}>Show Panel</a>
5  </div>
6  <div lwc:if={showPanel}>
7    <h1>This is the panel</h1>
8    <a href={noPanelUrl} onclick={handleNoPanelClick}>Hide Panel</a>
9  </div>
10</template>

1// pageStateChangeExample.js
2import { LightningElement, wire } from "lwc";
3import { CurrentPageReference, NavigationMixin } from "lightning/navigation";
4
5export default class PageStateChangeExample extends NavigationMixin(LightningElement) {
6  // Declare the currentPageReference variable in order to track it
7  currentPageReference;
8  // Injects the page reference that describes the current page
9  @wire(CurrentPageReference)
10  setCurrentPageReference(currentPageReference) {
11    this.currentPageReference = currentPageReference;
12
13    if (this.connected) {
14      // We need to have the currentPageReference, and to be connected before
15      // we can use NavigationMixin
16      this.generateUrls();
17    } else {
18      // NavigationMixin doesn't work before connectedCallback, so if we have
19      // the currentPageReference, but haven't connected yet, queue it up
20      this.generateUrlOnConnected = true;
21    }
22  }
23
24  showPanelUrl;
25  noPanelUrl;
26
27  // Determines the display for the component's panel
28  get showPanel() {
29    // Derive this property's value from the current page state
30    return this.currentPageReference && this.currentPageReference.state.c__showPanel == "true";
31  }
32
33  generateUrls() {
34    this[NavigationMixin.GenerateUrl](this.showPanelPageReference).then(
35      (url) => (this.showPanelUrl = url),
36    );
37    this[NavigationMixin.GenerateUrl](this.noPanelPageReference).then(
38      (url) => (this.noPanelUrl = url),
39    );
40  }
41
42  // Returns a page reference that matches the current page
43  // but sets the 'c__showPanel' page state property to 'true'
44  get showPanelPageReference() {
45    return this.getUpdatedPageReference({
46      c__showPanel: "true", // Value must be a string
47    });
48  }
49
50  // Returns a page reference that matches the current page
51  // but removes the 'c__showPanel' page state property
52  get noPanelPageReference() {
53    return this.getUpdatedPageReference({
54      // Removes this property from the state
55      c__showPanel: undefined,
56    });
57  }
58
59  // Utility function that returns a copy of the current page reference
60  // after applying the stateChanges to the state on the new copy
61  getUpdatedPageReference(stateChanges) {
62    // The currentPageReference property is read-only.
63    // To navigate to the same page with a modified state,
64    // copy the currentPageReference and modify the copy.
65    return Object.assign({}, this.currentPageReference, {
66      // Copy the existing page state to preserve other parameters
67      // If any property on stateChanges is present but has an undefined
68      // value, that property in the page state is removed.
69      state: Object.assign({}, this.currentPageReference.state, stateChanges),
70    });
71  }
72
73  connectedCallback() {
74    this.connected = true;
75
76    // If the CurrentPageReference returned before this component was connected,
77    // we can use NavigationMixin to generate the URLs
78    if (this.generateUrlOnConnected) {
79      this.generateUrls();
80    }
81  }
82
83  handleShowPanelClick(evt) {
84    evt.preventDefault();
85    evt.stopPropagation();
86    // This example passes true to the 'replace' argument on the navigate API
87    // to change the page state without pushing a new history entry onto the
88    // browser history stack. This prevents the user from having to press back
89    // twice to return to the previous page.
90    this[NavigationMixin.Navigate](this.showPanelPageReference, true);
91  }
92
93  handleNoPanelClick(evt) {
94    evt.preventDefault();
95    evt.stopPropagation();
96    this[NavigationMixin.Navigate](this.noPanelPageReference, true);
97  }
98}