RefreshView API Example

Using RefreshView API typically involves a chain of actions.

First, there must be a component somewhere on the page that can send a RefreshEvent event when a refresh is desired. In this example, the refreshButton component can signal a refresh.

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

1<!-- refreshButton.html -->
2<template>
3  <button label="Refresh Button" onclick={beginRefresh}>Refresh</button>
4</template>

Next, to participate in a view refresh, a component registers a handler method to be invoked after a container has received RefreshEvent. In this example, the handler method is registered in refreshHandler.js.

1//refreshHandler.js
2import { LightningElement } from "lwc";
3import { registerRefreshHandler, unregisterRefreshHandler } from "lightning/refresh";
4export default class RefreshHandler extends LightningElement {
5  refreshHandlerID;
6  connectedCallback() {
7    this.refreshHandlerID = registerRefreshHandler(this, this.refreshHandler);
8    // if the component runs in an org with Lightning Locker instead of Lightning Web Security (LWS), use
9    // this.refreshHandlerID = registerRefreshHandler(this.template.host, this.refreshHandler.bind(this));
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}

Finally, there must be a component somewhere on the page that registers to receive RefreshEvent. In this example, refreshContainer registers to receive refresh events. It starts a refresh process when an event is received.

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

Put the refreshHandler and refreshButton components in the refreshContainer template, including your namespace in the tags. c is the default namespace in this example.

1<!-- refreshContainer.html -->
2<template>
3  <!-- Ensure handler exists within structure of container -->
4  <div>
5    <c-refresh-handler></c-refresh-handler>
6  </div>
7  <div>
8    <c-refresh-button></c-refresh-button>
9  </div>
10</template>

See Also