Skip to main content

Refresher

Open in ChatGPT
Shadow dwc-refresher 25.00
Java API

Pull-to-refresh is a common pattern in mobile and tap-friendly interfaces, and the Refresher component brings it to scrollable containers in webforJ. As users swipe downward past a configurable threshold, it transitions through visual states: pull, release, and refreshing, each with a customizable icon and localized text. It pairs well with InfiniteScroll for reloading or resetting content through gesture-based input.

Instantiation and internationalization​

Add a Refresher by instantiating it and registering a refresh listener. When refresh operations complete, call finish() to reset the component to its idle state.

How to activate the Refresher

To activate the Refresher, click and drag downward from the top of the scrollable area. While this gesture is familiar on mobile, it's less common on desktop—make sure to hold and pull with your mouse.

Show Code

This approach is commonly used to refresh paginated lists or restart infinite scroll loading.

Internationalization​

Each state label can also be localized using the RefresherI18n object. The three states are:

  • Pull: Initial gesture text (e.g., "Pull down to refresh")
  • Release: Trigger threshold reached (e.g., "Release to refresh")
  • Refresh: Loading state (e.g., "Refreshing")

This allows multilingual support and branding adjustments as needed.

Show Code

Icon customization​

You can change the Icons used for the pull/release and refreshing stages using either a predefined Icon or an Icon URL. These are useful when you want to apply branding or a custom animation.

Show Code

Pull behavior configuration​

Threshold​

Set how far the user must pull down (in pixels) before triggering the refresh:

refresher.setThreshold(80); // default: 80px

Threshold maximum​

To define the maximum pull distance allowed, use the setThresholdMax() method:

refresher.setThresholdMax(160);

These thresholds control the gesture sensitivity and resistance curve.

State management​

The Refresher component maintains its own internal state and communicates state changes through events. When a user pulls down past the defined threshold, the Refresher emits a refresh event that you can respond to by registering an onRefresh() listener.

Inside this listener, you’re expected to perform whatever operation is required—such as fetching new data or resetting a list—and then explicitly call:

refresher.finish();
Missing finish()

If you forget to call finish(), the refresher will remain in the loading state indefinitely.

You can also programmatically disable the Refresher at any time to prevent the user from triggering refresh behavior:

refresher.setEnabled(false);

This is useful when refreshes should be temporarily disallowed—for instance, during a loading screen or while another critical process is running.

Styling​

Themes​

The Refresher component supports multiple themes to visually distinguish different states or to match your app's look and feel. Themes can be applied using the setTheme() method.

The following sample cycles through all available themes each time you pull to refresh, giving you a live preview of how the Refresher looks across different themes:

Show Code

Loading...