Repository navigation
Description
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: bridgelessrequestAnimationFrameiscreateTimer(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 whentimer.targetTime < frameTimeNanos / 1e6.frameTimeNanosis the vsync timestamp, andtargetTimeis the time the timer was registered.- So a rAF registered after vsync N's timestamp, but before vsync N's
doFrameruns, is skipped and waits for vsync N+1. The JS thread receivesdoFramea 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
preferredFrameRateRangeitself, runs a WebGPU loop at 119.8 fps. So the device is not in Low Power Mode. - iOS has no registration cliff:
RCTTimingcompares 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:
AChoreographeron a looper thread (Android),CADisplayLinkon a run loop thread withpreferredFrameRateRangeup 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 theCallInvoker. - 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).rubennortereplied: "we need to rewrite the entire implementation forrequestAnimationFramebecause, 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 callingsetTimeout(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
preferredFramesPerSecondon the Animated and perf monitor display links and removes the hard-coded 60 fps frame length. It does not touchRCTDisplayLink, so JSrequestAnimationFramestays 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.doFramere-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 wherepreferredFrameRateRangewould 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
- #32828 "Enabling ProMotion on iPhone 13 Pro & iPad Pro" (January 2022). It only changed the template's
Info.plistandAppDelegate. It was closed two days after opening; the last review comment asks how to verify that animations run at the higher frame rate. The tables in this issue are that verification. enableOnDemandReactChoreographer(2023 to 2024), pointed out byjavachein [Android] Idle apps keep the Choreographer running at ~60 doFrames/s (zero work, zero frames rendered) — four frame callbacks re-arm unconditionally #58367: #41606 scheduled the Animated Choreographer callback only while animations were running, and #41658 did the same for event dispatch. Schedule a Choreographer callback only if there is ongoing animation #41606 was backed out in #41671 ("caused performace problems with react app"), and the flag was removed in #43044. According to the analysis in [Android] Idle apps keep the Choreographer running at ~60 doFrames/s (zero work, zero frames rendered) — four frame callbacks re-arm unconditionally #58367, the experiment never covered the timers callback. It is a caution for the "only request a native frame while the queue is non-empty" part: every path that queues work has to re-arm the frame callback.
Open points for a fix
- Check that the change doesn't reorder
setTimeoutversus rAF in a way existing tests rely on. - Callback order: the Android timer queue still sorts by target time only (
JavaTimerManager.kt, thePriorityQueuecomparator), which is the causerubennorteidentified in requestAnimationFrame callback order is nondeterministic #48005. A first-in, first-out frame queue gives rAF callbacks a defined order. - Test: a Fantom or instrumentation test that registers a rAF after the vsync timestamp but before
doFrame, and expects it to run on that frame. - Coordinate with Android: stop re-arming the idle TIMERS_EVENTS Choreographer frame callback (behind feature flag) #58375 (same
doFrame) and with [iOS] Create RCTDisplayLink's CADisplayLink when it is scheduled on the JS run loop #59778 and Let iOS JS timers sleep until they are due #59317 (same JS display link), so the changes don't conflict.
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.
- Build RNTester with the reproducer on a 120 Hz Android phone (measured here on a Galaxy S25 Edge) and open the Playground tab.
- Select 5 ms of JS work per callback: the counter reads about 120 callbacks/s.
- Select 7 or 8 ms, still under the 8.3 ms frame budget: the counter drops toward 60 callbacks/s. Expected: about 120.
- Tap "Next frame requested at the END of the callback" to request it at the start instead: the counter returns to about 120.
- On a ProMotion iPhone (measured here on an iPhone 14 Pro), add
CADisableMinimumFrameDurationOnPhone(true) topackages/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.setRequestedFrameRateon the TextureView doesn't change that. - To check, look for
setFrameRate= {uid, 60 Hz}indumpsys SurfaceFlinger, or for "is small dirty" and "getFrameRateOverrides: overriding to 60" in a Perfetto trace with thegfxatrace 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
Activity