Framework7 pull-to-refresh: version-specific implementation, theme adaptation, and common failure modes

Problem: pull-to-refresh silent or misstyled

When a Framework7 list fails to trigger a refresh on drag, or the indicator appears in a default theme that does not match your app, the cause is usually one of three things: the version-specific API, a clipped container, or an omitted theme setting.

Version matters: v5 inline handler vs v6 dedicated component

Framework7 v5 relies on an inline onPullToRefresh handler attached to a container with the pull-to-refresh class. The framework fires a refresh event after the user drags past a default 80-pixel threshold, but the developer must manually load new data and update the list.

Framework7 v6 introduces the dedicated pull-to-refresher component. This component replaces the inline handler with a declarative widget that accepts configurable distance (in pixels), text for loading state labels, and a theme prop that drives the spinner's appearance. The component still fires a refresh event, but the visual and configurational surface is different.

Smallest suitable design

• The container must carry the pull-to-refresh (v5) or pull-to-refresher class.
• The container must have a defined height; a parent with overflow: hidden will clip the drag gesture and prevent the feature from activating.
• Initializing Framework7 (via myApp.init() or the framework's auto-init) is required before the event listener attaches.

Theme adaptation

Framework7 ships with three default themes iOS Material Design and Aurora. Each theme styles the refresh indicator differently. In v5 the theme is usually inferred from the page's theme parameter. In v6 the pull-to-refresher component accepts an explicit theme attribute. Omitting it can result in a default indicator that does not match your app's visual language.

pull-to-refresher theme='ios' distance=80 @refresh='onRefresh'

Replace theme='ios' with theme='md' or theme='aurora' as needed. The text prop can also be set to customize Loading... and Release to refresh labels.

Operational checks

1. Add the appropriate class to a list container that has sufficient height and no overflow: hidden.
2. Initialize Framework7 and ensure no JavaScript errors prevent event binding.
3. Drag down beyond the configured distance (default 80px in v5 configurable in v6).
4. Open the browser console or device log and confirm the refresh event fires.
5. Verify the spinner adopts the expected theme color.

Failure modes and conditions that would change the design

• Clipped gesture: If any parent element sets overflow: hidden or the container has a fixed height smaller than the drag distance pull-to-refresh will not trigger. The fix is to promote the list to a full-screen or scrollable container without clipping.
• Missing theme mismatch: In v6 leaving out theme yields a generic spinner. Explicitly set the theme prop to match your page's theme.
• Version drift: Code written for v5's onPullToRefresh will not work with v6's pull-to-refresher without refactoring. A redesign is required when migrating.

Diagnostic decision table

If the refresh event does not fire after dragging past the threshold double-check that no ancestor has overflow: hidden and that the Framework7 version matches the expected API surface.