Controlled PullToRefresh

[imsyf]

Currently PullToRefresh status is handled internally by awaiting promise passed to onRefresh props.
Would it be possible to control PullToRefresh status with React state?

It would be useful when:

1. We need to update some UI based on this component status, outside of renderText props (though right now it can be done by utilizing CSS has selector)
2. We interact with non-promise-based refresh function, such as Next.js router.refresh function

Therefore I think it's pretty important to have a way to sync its status with parent state

[dosubot[bot]]

Hi @imsyf! I'm Dosu and I’m helping the ant-design-mobile team.

Currently, PullToRefresh in ant-design-mobile does not support controlling its status via React state or a "controlled mode"—the status is managed internally and transitions are tied to the promise returned by the onRefresh prop. There is no prop or API for syncing status with parent state or for handling non-promise-based refresh functions directly. The only way to update external UI based on PullToRefresh status is by customizing renderText or using CSS selectors like :has, but this does not provide true state synchronization or external control [docs] [source].

There are multiple feature requests for a controlled mode or ref-based API (e.g., ref.current.startRefresh, ref.current.completeRefresh), and maintainers have acknowledged the need for this, but it is not implemented yet [issue #6270] [issue #5653].

For now, if you need to sync external state, you can wrap your onRefresh handler to set your own React state before and after the refresh logic, but this won't control the PullToRefresh UI itself. For non-promise-based refresh functions, you could create a promise wrapper around your logic, but again, this is a workaround and not a true controlled solution.

If you need full external control, you'll need to wait for a future update or consider a custom implementation.

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.

[imsyf]

@dosubot those issues you mentioned are old but still open, what's the consensus from team? is it something that can be done?

moreover what changes needed to accomplish that? let's see some code diffs

[dosubot[bot]]

There’s no recent team consensus or active work on controlled mode for PullToRefresh—the relevant issues are still open and acknowledged, but not prioritized or scheduled for development [source: code, issues].

Technically, it’s feasible. The current implementation manages status internally via a useState and transitions based on user gestures and the promise from onRefresh. To support controlled mode, you’d need to:

• Add a status prop (or a boolean refreshing prop for simpler use cases).
• Gate internal state updates so they respect the external prop when provided.
• Optionally add an onStatusChange callback for two-way sync.
• Refactor the drag handler and refresh logic to use the external status when present.
• Consider exposing ref methods (e.g., startRefresh, completeRefresh) for imperative control.

Here’s a rough code diff to illustrate the main changes:

- const [status, setStatus] = useState<PullStatus>('pulling')
+ const isControlled = 'status' in props
+ const [internalStatus, setInternalStatus] = useState<PullStatus>('pulling')
+ const status = isControlled ? props.status : internalStatus

  useDrag(
    state => {
-     if (status === 'refreshing' || status === 'complete') return
+     if (status === 'refreshing' || status === 'complete') return
      // ...existing drag logic...
-     setStatus(height > threshold ? 'canRelease' : 'pulling')
+     if (!isControlled) setInternalStatus(height > threshold ? 'canRelease' : 'pulling')
+     props.onStatusChange?.(height > threshold ? 'canRelease' : 'pulling')
    },
    // ...
  )

- async function doRefresh() {
-   api.start({ height: headHeight })
-   setStatus('refreshing')
-   try {
-     await props.onRefresh()
-     setStatus('complete')
-   } catch (e) {
-     reset()
-     throw e
-   }
-   if (props.completeDelay > 0) {
-     await sleep(props.completeDelay)
-   }
-   reset()
- }
+ async function doRefresh() {
+   api.start({ height: headHeight })
+   if (!isControlled) setInternalStatus('refreshing')
+   props.onStatusChange?.('refreshing')
+   try {
+     await props.onRefresh()
+     if (!isControlled) setInternalStatus('complete')
+     props.onStatusChange?.('complete')
+   } catch (e) {
+     reset()
+     throw e
+   }
+   if (props.completeDelay > 0) {
+     await sleep(props.completeDelay)
+   }
+   reset()
+ }

  // ...rest of the component...

You’d also need to update docs and tests. The main challenge is keeping animation and gesture logic in sync with external state, especially if the parent changes status asynchronously.

For reference, the old ListView used a refreshing prop for this purpose [ListView example].

Let me know if you want a deeper dive or a more complete diff!

To reply, just mention @dosu.

---

Docs are dead. Just use Dosu.

[imsyf]

@dosubot could you open a PR to run the tests?

[dosubot[bot]]

I can't open PRs or run tests directly in the repository—my role is to provide guidance, code suggestions, and technical support. If you want help refining the controlled PullToRefresh implementation or reviewing diffs before you open a PR, let me know!

To reply, just mention @dosu.

---

Share context across your team and agents. Try Dosu.