Use RefreshView API

To use RefreshView API, import the lightning/refresh module.

The lightning/refresh module also replaces force:refreshView for Aura and exposes:

The RefreshEvent event that a module can fire to signal a refresh.
Methods that allow components to register to receive the dispatched refresh event and begin the refresh process.
Methods that allow components to register callback methods that are invoked as part of the refresh process.
Status definitions such as RefreshComplete, RefreshCompleteWithError, and RefreshError.

Register Refresh Handler Methods in LWC

You must register components belonging to refresh-enabled views to be included in the refresh process.

To participate in a view refresh, a component registers a handler method. Use the registerRefreshHandler() method in a component’s connectedCallback() to register a handler method.

The parameters passed in the registerRefreshHandler() method require a different format when the component is running in an org that hasn’t enabled Lightning Web Security (LWS) and is still using Lightning Locker.

Important

A handler method is invoked after a container has received a RefreshEvent. Registered containers compose a “refresh tree” of registered refresh handlers, the order of which emulates the DOM. The containers then invoke the callback refresh methods of the participant components, which have registered a refresh handler.

Example for Org with LWS Enabled

1import { LightningElement } from "lwc";
2import { registerRefreshHandler, unregisterRefreshHandler } from "lightning/refresh";
3export default class RefreshHandler extends LightningElement {
4  refreshHandlerID;
5  connectedCallback() {
6    this.refreshHandlerID = registerRefreshHandler(this, this.refreshHandler);
7  }
8  disconnectedCallback() {
9    unregisterRefreshHandler(this.refreshHandlerID);
10  }
11  refreshHandler() {
12    // example usage case for refresh participant
13    // fetch some data and report status once complete
14    let endPoint = "https://api.<your company>.com";
15    return new Promise((resolve) => {
16      fetch(endPoint, {
17        method: "GET",
18      });
19      resolve(true);
20    });
21  }
22}

Example for Org with Lightning Locker Enabled

1import { LightningElement } from "lwc";
2import { registerRefreshHandler, unregisterRefreshHandler } from "lightning/refresh";
3export default class RefreshHandler extends LightningElement {
4  refreshHandlerID;
5  connectedCallback() {
6    this.refreshHandlerID = registerRefreshHandler(
7      this.template.host,
8      this.refreshHandler.bind(this),
9    );
10  }
11  disconnectedCallback() {
12    unregisterRefreshHandler(this.refreshHandlerID);
13  }
14  refreshHandler() {
15    // example usage case for refresh participant
16    // fetch some data and report status once complete
17    let endPoint = "https://api.<your company>.com";
18    return new Promise((resolve) => {
19      fetch(endPoint, {
20        method: "GET",
21      });
22      resolve(true);
23    });
24  }
25}

Registered refresh methods in the refresh tree are invoked in a breadth-first order from the registered container’s node. This approach ensures that higher level (parent) handlers resolve before lower level (child) handlers are invoked.

The registered refresh handler callback must:

Return a Promise that resolves to a Boolean:
- true if the component has completed operations for a refresh and the refresh process can continue down the refresh tree from this node
- false to prevent the refresh process from continuing to child elements of this node
Perform necessary view update operations in accordance with current state.
Ensure data and state are resynchronized, if necessary.
Show appropriate UI during the process, such as spinners or toasts.

You must also unregister your component’s handler methods in disconnectedCallback() as shown in the previous example.

Signal a Refresh with RefreshEvent

To start a view refresh, fire the RefreshEvent event, defined in lightning/refresh. This event makes a request to a container to begin the refresh process. This event can be fired from any component.

1import { LightningElement } from "lwc";
2import { RefreshEvent } from "lightning/refresh";
3
4export default class RefreshButton extends LightningElement {
5  // signal a refresh programmatically
6  // or via a button click
7  beginRefresh() {
8    this.dispatchEvent(new RefreshEvent());
9  }
10}

Register to Receive RefreshEvent

To begin the refresh process on the user’s view, an application controller in each container must register to receive RefreshEvent. Use the registerRefreshContainer() method in the container’s connectedCallback() to register to receive RefreshEvent.

The parameters passed in the registerRefreshContainer() method require a different format when the component is running in an org that hasn’t enabled LWS and is still using Lightning Locker.

Important

If you’re adding a component to an active page, you don’t need to create a container to receive RefreshEvent. Add a container only if you want to determine the scope of your refresh.

Note

Example for Org with LWS Enabled

1import { LightningElement } from "lwc";
2import {
3  registerRefreshContainer,
4  unregisterRefreshContainer,
5  REFRESH_ERROR,
6  REFRESH_COMPLETE,
7  REFRESH_COMPLETE_WITH_ERRORS,
8} from "lightning/refresh";
9
10export default class RefreshContainer extends LightningElement {
11  refreshContainerID;
12  connectedCallback() {
13    this.refreshContainerID = registerRefreshContainer(this, this.refreshContainer);
14  }
15  disconnectedCallback() {
16    unregisterRefreshContainer(this.refreshContainerID);
17  }
18  refreshContainer(refreshPromise) {
19    console.log("refreshing");
20    return refreshPromise.then((status) => {
21      if (status === REFRESH_COMPLETE) {
22        console.log("Done!");
23      } else if (status === REFRESH_COMPLETE_WITH_ERRORS) {
24        console.warn("Done, with issues refreshing some components");
25      } else if (status === REFRESH_ERROR) {
26        console.error("Major error with refresh.");
27      }
28    });
29  }
30}

Example for Org with Lightning Locker Enabled

1import { LightningElement } from "lwc";
2import {
3  registerRefreshContainer,
4  unregisterRefreshContainer,
5  REFRESH_ERROR,
6  REFRESH_COMPLETE,
7  REFRESH_COMPLETE_WITH_ERRORS,
8} from "lightning/refresh";
9
10export default class RefreshContainer extends LightningElement {
11  refreshContainerID;
12  connectedCallback() {
13    this.refreshContainerID = registerRefreshContainer(
14      this.template.host,
15      this.refreshContainer.bind(this),
16    );
17  }
18  disconnectedCallback() {
19    unregisterRefreshContainer(this.refreshContainerID);
20  }
21  refreshContainer(refreshPromise) {
22    console.log("refreshing");
23    return refreshPromise.then((status) => {
24      if (status === REFRESH_COMPLETE) {
25        console.log("Done!");
26      } else if (status === REFRESH_COMPLETE_WITH_ERRORS) {
27        console.warn("Done, with issues refreshing some components");
28      } else if (status === REFRESH_ERROR) {
29        console.error("Major error with refresh.");
30      }
31    });
32  }
33}

Passing this to registerRefreshContainer binds an event listener to the element for RefreshEvent. When a registered refresh container receives RefreshEvent, the refresh process begins on its refresh tree.

RefreshEvent follows DOM event bubbling rules, so the refresh container beginning this process is the nearest registered ancestor to the signaling component.

Note

The registered container’s callback — in this example refreshContainer() — is invoked when the container receives RefreshEvent. The callback receives a Promise as a parameter when the refresh process begins. When the refresh process finishes, this Promise is resolved with a RefreshStatus value.

To manage processes surrounding the refresh, use the registered container’s callback method. For example:

Instrumenting begin/end
Showing spinners
Error handling
Toasts

As shown in the RefreshEvent example, you must also unregister the view controller as a refresh container in disconnectedCallback() using the unregisterRefreshContainer() method.

See Also