registerRefreshContainer()

Registers a container to receive the dispatched refresh event and begin the refresh process when the event is received. To use the RefreshView API, there must be a component somewhere on the page that registers to receive RefreshEvent.

  • contextElement—(Required) An HTMLElement representing the container to receive a refresh event.
  • providerMethod—(Required) A Function identifying the callback method to be invoked when the refresh process begins. This callback receives a Promise as a parameter that represents the status of the overall refresh process.

Returns a numeric refreshNode.handle value that uniquely identifies the container that is to receive refresh events. You can pass this value to unregisterRefreshContainer() to stop the component from receiving refresh events.

Use the registerRefreshContainer() method in a container’s connectedCallback() to register to receive a RefreshEvent signal.

If the component must run in an org that has Lightning Locker enabled, use the modified format of the registerRefreshContainer() parameters shown in the code comments inside connectedCallback().

When you pass this to registerRefreshContainer(), event listeners are bound to the element for RefreshEvent.

When RefreshEvent is received by a registered refresh container, 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. To refresh the entire page, you must either register a container at the proper level or allow the page host to act as the container.

The registered container 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. This Promise is resolved with a RefreshStatus value when the refresh process finishes.

The registered container callback method can be used to manage processes surrounding the refresh, such as:

  • Instrumenting begin/end
  • Showing spinners
  • Error handling
  • Toasts

You must unregister the view controller as a refresh container in disconnectedCallback() using the unregisterRefreshContainer() method.