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.

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 LWS and is still using Lightning Locker.

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

Example for Org with Lightning Locker Enabled

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.

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.

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.

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.

Example for Org with LWS Enabled

Example for Org with Lightning Locker Enabled

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.

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