Skip to content

requestAnimationFrame is not driven by the display (Choreographer, CADisplayLink): 120 Hz loops drop to 60 fps on Android, and it is capped at 60 Hz on ProMotion iPhones #60216

Open

Description

@wcandillon

Description

In a browser, requestAnimationFrame is a frame callback. The display's vsync starts a frame, every callback queued for that frame runs once, and all of them receive the frame's timestamp.

In React Native, requestAnimationFrame is a timer. Bridgeless requestAnimationFrame(cb) is setTimeout(cb, 0), and the code comment says so. The timer queue happens to be polled from a display callback (Choreographer on Android, a CADisplayLink on iOS), but nothing ties a rAF callback to a frame: there is no per-frame queue, no frame timestamp, and no guarantee that a callback queued before a frame runs in that frame.

This has two measurable effects:

  • Android: at 120 Hz, a render loop drops to exactly 60 fps once its callback takes more than about 6.3 ms, although the frame budget is 8.3 ms.
  • iOS: rAF is capped at 60 Hz on ProMotion devices, even when the app opts in to 120 Hz.

Expected: requestAnimationFrame runs once per display frame, at the display's rate, for any callback that fits in the frame budget.

The fix proposed below is to make requestAnimationFrame a real animation-frame queue, driven by the platform's display source: Choreographer on Android, CADisplayLink on iOS. React Native maintainers have already described rAF as "glorified timers" that need a rewrite (see Prior art). No open issue or PR does that work today.

Android: the 120 Hz cliff

const loop = () => {
  render();                    // ~7 ms of JS
  requestAnimationFrame(loop); // re-registered at the end, like most loops
};
requestAnimationFrame(loop);

The GPU is mostly idle and nothing else is busy. The same loop holds 120 fps when the next frame is requested at the start of the callback. Browsers behave that way regardless of where requestAnimationFrame is called.

Root cause:

  • ReactCommon/react/runtime/TimerManager.cpp: bridgeless requestAnimationFrame is createTimer(cb, delay 0). The code comment already says this is "the same as setTimeout(0)" and "may change in the future".
  • ReactAndroid/.../modules/core/JavaTimerManager.kt, TimerFrameCallback.doFrame: a timer only fires when timer.targetTime < frameTimeNanos / 1e6. frameTimeNanos is the vsync timestamp, and targetTime is the time the timer was registered.
  • So a rAF registered after vsync N's timestamp, but before vsync N's doFrame runs, is skipped and waits for vsync N+1. The JS thread receives doFrame a little after vsync, so the usable budget is about 6.3 ms at 120 Hz (and about 14 ms at 60 Hz, which is why this rarely shows up on 60 Hz phones).
  • Smaller issue: the callback receives performance.now() at call time, not the frame time, so animations sharing a frame see different timestamps.

Evidence (Galaxy S25 Edge, 120 Hz, RN 0.88.1, Perfetto):

JS time per callback fps, stock rAF fps, frame-aligned rAF
5.9 ms 120 120
6.4 ms 109 120
6.9 ms 94 120
7.5 ms 60 120
5 ms JS + 75% GPU load 70 120

The "frame-aligned" column is a JS-only shim: one native rAF per frame flushes every callback queued before it, and requests the next native frame before running them.

iOS: capped at 60 Hz on ProMotion devices

RCTDisplayLink creates its CADisplayLink without setting preferredFrameRateRange. On ProMotion iPhones that keeps it at 60 Hz, even when the app opts in with CADisableMinimumFrameDurationOnPhone. Bridgeless timers, and so requestAnimationFrame, run on that display link.

iPhone 14 Pro, RN 0.88.1 (prebuilt core), WebGPU Cube, rAF rate:

JS time per callback Stock Display link set to 80-120 Hz
1.4 ms 60 120
5 to 8.2 ms 60 120
10 ms 60 98
  • The 120 Hz column was produced by swizzling +[CADisplayLink displayLinkWithTarget:selector:] for the _jsThreadUpdate: selector, because the core is prebuilt.
  • On the same phone, Worklets' UI runtime, which sets preferredFrameRateRange itself, runs a WebGPU loop at 119.8 fps. So the device is not in Low Power Mode.
  • iOS has no registration cliff: RCTTiming compares timers against the current time when the display link fires. Requesting the next frame at the start or the end of the callback made no difference.

Proposed change

Implement rAF in TimerManager / RuntimeScheduler as a real animation-frame queue, driven by the platform display source (Choreographer on Android, CADisplayLink on iOS) and matching the HTML "run the animation frame callbacks" step:

  • Native frame callback swaps the queue and runs every callback that was queued before it.
  • Callbacks registered during the flush go to the next frame.
  • Every callback receives the same frame timestamp (vsync time, in the performance.now() timebase).
  • Only request a native frame while the queue is non-empty, so idle apps don't wake up every vsync.

This removes the dependency on timer ordering and makes Android and iOS behave the same.

iOS: set preferredFrameRateRange on the JS display link (for example CAFrameRateRangeMake(80, maxFPS, maxFPS), using UIScreen.maximumFramesPerSecond), ideally only while animation-frame callbacks are pending. This avoids keeping the display at 120 Hz while the app is idle.

Stopgap (Android only): in doFrame, compare against the time doFrame runs (nanoTime()), not frameTimeNanos. Every timer that has expired by the time the frame callback runs fires on that frame. This is a one-line change and also helps setTimeout(0) chains. It removes the cliff, but rAF stays a timer.

Working implementation in user land: react-native-webgpu's requestAnimationFrame

React Native WebGPU now exports a requestAnimationFrame that implements the proposed change outside of React Native (wcandillon/react-native-webgpu#636). It is the motivating example for this change.

  • A native display source on a thread of its own: AChoreographer on a looper thread (Android), CADisplayLink on a run loop thread with preferredFrameRateRange up to 120 (iOS).
  • Browser semantics: each frame runs the callbacks queued before it, callbacks queued during the flush go to the next frame, and every callback of a frame gets the same timestamp (vsync time in the performance.now() timebase). Callbacks are posted to the JS thread through the CallInvoker.
  • A loop that overruns its frame is delivered immediately if the current frame is still fresh and hasn't run its callbacks yet. This is the equivalent of the Android stopgap: no frame is skipped just because the callback was queued after the vsync timestamp.

Final measurements, same WebGPU cube with busy work per frame, frames presented per second (Perfetto on Android, on-screen counter on iOS):

Device JS time per callback Stock rAF react-native-webgpu rAF
Galaxy S25 Edge, 120 Hz 0 ms 117 119
Galaxy S25 Edge, 120 Hz 7 ms 59 119
Galaxy S25 Edge, 120 Hz 10 ms 58.5 94
iPhone 14 Pro, ProMotion 0 ms 60 120
iPhone 14 Pro, ProMotion 7 ms 60 120
iPhone 14 Pro, ProMotion 10 ms 60 98

At 10 ms per callback the frame can't fit in 8.3 ms. The aligned version still gets 94 to 98 fps because an overrunning loop runs again in the frame it overran into, instead of halving to 60.

Prior art

Searched react/react-native issues and pull requests, open and closed, on 2026-11-22. No open issue or PR covers the Android registration cliff or the missing preferredFrameRateRange. The three code sites named above are unchanged on main (d6ea9fc1eed), and nothing in the core sets preferredFrameRateRange anywhere.

Maintainers already describe rAF as a timer

  • #48005 "requestAnimationFrame callback order is nondeterministic" (gaearon, November 2024). rubennorte replied: "we need to rewrite the entire implementation for requestAnimationFrame because, apart from the problems you mentioned, it doesn't provide semantics that resemble anything on Web. They're basically glorified timers." He added it to the backlog. The stale bot closed the issue in June 2025 (not planned).
  • #47888 "[android][newarch] performance / requestAnimationFrame behavior changes" (closed December 2024). blakef: the implementation "isn't to web-spec, it's basically the equivalent of calling setTimeout(callback, 0)", "so you can't use it to measure frame rate".

Open issues about refresh rate (symptom only, no root cause)

  • #29333 "React native does not support screen refresh rate" (open since July 2020, 57 comments).
  • #32703 "No support for 120Hz in React Native" (open since December 2021, iOS ProMotion).

Open PRs that touch the same code

  • #51775 "feat: support 120fps for Animated" (Callstack, June 2025). It sets preferredFramesPerSecond on the Animated and perf monitor display links and removes the hard-coded 60 fps frame length. It does not touch RCTDisplayLink, so JS requestAnimationFrame stays at 60 Hz. Changes were requested in June 2025; the author asked for a re-review in August 2025 and has had no review since.
  • #58375 "Android: stop re-arming the idle TIMERS_EVENTS Choreographer frame callback" (part of #58367). Behind disableIdleTimersFrameCallbackRearmAndroid, TimerFrameCallback.doFrame re-posts itself only while the timer queue is non-empty. It edits the same function as the Android stopgap, and it is the timer version of "only request a native frame while the queue is non-empty".
  • #59778 "[iOS] Create RCTDisplayLink's CADisplayLink when it is scheduled on the JS run loop". It moves the creation of the display link into addToRunLoop:, which is the line where preferredFrameRateRange would be set.
  • #59317 "Let iOS JS timers sleep until they are due" (Software Mansion). Behind sleepUntilNextTimerIOS, the JS display link only runs for timers due within two frames, rAF included. It fits with raising the frame rate only while rAF callbacks are pending.

Earlier attempts

Open points for a fix

Steps to reproduce

The reproducer is an RNTesterPlayground.js that runs a requestAnimationFrame loop with a chosen amount of JS work per callback, and shows the number of callbacks per second. It uses React Native only.

  1. Build RNTester with the reproducer on a 120 Hz Android phone (measured here on a Galaxy S25 Edge) and open the Playground tab.
  2. Select 5 ms of JS work per callback: the counter reads about 120 callbacks/s.
  3. Select 7 or 8 ms, still under the 8.3 ms frame budget: the counter drops toward 60 callbacks/s. Expected: about 120.
  4. Tap "Next frame requested at the END of the callback" to request it at the start instead: the counter returns to about 120.
  5. On a ProMotion iPhone (measured here on an iPhone 14 Pro), add CADisableMinimumFrameDurationOnPhone (true) to packages/rn-tester/RNTester/Info.plist, which RNTester does not set, and open the Playground: the counter reads 60 callbacks/s at every setting, including 0 ms. Expected: about 120.

Measuring on Android: animate most of the screen. This is an Android platform behavior, not React Native, and the reproducer repaints its whole surface on every callback for that reason.

  • On the Galaxy S25 Edge (One UI, API 37), when the window's damage covers less than about half of the display, SurfaceFlinger tags the layer "small dirty", votes 60 Hz, and applies that vote to the whole app through frame-rate override. The app then runs at 60 whatever schedules its frames. View.setRequestedFrameRate on the TextureView doesn't change that.
  • To check, look for setFrameRate= {uid, 60 Hz} in dumpsys SurfaceFlinger, or for "is small dirty" and "getFrameRateOverrides: overriding to 60" in a Perfetto trace with the gfx atrace category. A canvas at 48% of the screen read 59.5 fps for every scheduler.
  • Upstream precedent: AOSP "SF: Suppress frame rate when small area updating" (bug 281720315) and "VRR: Allowlist for small area detection". In AOSP, small-dirty frames only drop out of the heuristic vote (NoVote), and the thresholds come from a per-package allowlist (config_smallAreaDetectionAllowlist, package:threshold). Two things on the Samsung go further and look like OEM tuning, not documented behavior: an explicit 60 Hz vote, and applying it to an app that is unlikely to be on any allowlist.

React Native Version

0.88.1

Affected Platforms

Runtime - Android, Runtime - iOS

Output of npx @react-native-community/cli info

System:
  OS: macOS 26.6.2
  CPU: (18) arm64 Apple M5 Max
  Memory: 3.49 GB / 64.00 GB
  Shell:
    version: "5.9"
    path: /bin/zsh
Binaries:
  Node:
    version: 22.22.2
    path: ~/.nvm/versions/node/v22.22.2/bin/node
  Yarn:
    version: 3.6.4
    path: ~/.nvm/versions/node/v22.22.2/bin/yarn
  npm:
    version: 11.19.1
    path: ~/tmp/tmp/react-native-webgpu/node_modules/.bin/npm
  Watchman: Not Found
Managers:
  CocoaPods:
    version: 1.16.2
    path: /opt/homebrew/bin/pod
SDKs:
  iOS SDK:
    Platforms:
      - DriverKit 27.2
      - iOS 27.2
      - macOS 27.2
      - tvOS 27.2
      - visionOS 27.2
      - watchOS 27.2
  Android SDK:
    Android NDK: 27.2.12479018
IDEs:
  Android Studio: 2026.1 AI-261.26222.65.2614.16379836
  Xcode:
    version: 27.2/27B52
    path: /usr/bin/xcodebuild
Languages:
  Java:
    version: 17.0.20.1
    path: /opt/homebrew/opt/openjdk@17/libexec/openjdk.jdk/Contents/Home/bin/javac
  Ruby:
    version: 2.6.10
    path: /usr/bin/ruby
npmPackages:
  "@react-native-community/cli": Not Found
  react: Not Found
  react-native: Not Found
  react-native-macos: Not Found
npmGlobalPackages:
  "*react-native*": Not Found
Android:
  hermesEnabled: true
  newArchEnabled: true
iOS:
  hermesEnabled: true
  newArchEnabled: true

Stacktrace or Logs

No crash and no error message. The failure is a frame rate: see the measurements in the description.

MANDATORY Reproducer

https://gist.github.com/wcandillon/07cb82865ee0bb54bee56a1f12c3dd2d

Screenshots and Videos

No response

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions