Repository navigation
Description
Summary
Every React Native Android app keeps the main-thread Choreographer armed at ~60 doFrames/second while completely idle in the foreground — no timers pending, no animations running, no mount items, zero frames rendered — on every Android version we tested (API 28 → 36). It is pure CPU/battery waste present in stock template apps with zero app code or third-party dependencies involved.
Measured on a stock react-native@0.86.3 template app (npx @react-native-community/cli init --version 0.86.3), Release build, app foregrounded and settled, no interaction:
| Device | API | doFrames / 10s idle | median / p90 / max doFrame | App process CPU | Frames rendered (gfxinfo) |
|---|---|---|---|---|---|
| OnePlus 3T (SD820) | 28 | 597–598 | 1.95 / 2.81 / 15.86 ms | ~22.5% | 0 |
| OnePlus 5T (SD835) | 29 | 599–601 | 0.99–1.82 / 2.11 / 14.67 ms | ~9.3% | 0 |
| OPPO Find X8 (Dimensity 9400) | 36 | 587–601 | 0.67–0.86 / 0.94–1.21 / 2.83 ms | ~3.5–6.8% | 0 |
The loop stops when the app is backgrounded (host pause) and restarts on resume. iOS is unaffected (Choreographer is Android-only).
Root cause
Four Android frame callbacks re-post themselves unconditionally at the end of their own doFrame, and are initially armed at host resume, with no pending-work check:
| # | Class | Re-arm site (0.86.3) |
|---|---|---|
| 1 | JavaTimerManager$TimerFrameCallback |
JavaTimerManager.kt:317 — posts itself after every frame even with an empty timer queue |
| 2 | FabricEventDispatcher$ScheduleDispatchFrameCallback |
FabricEventDispatcher.kt:153 — doFrame re-posts unless stopped; events are actually dispatched synchronously in dispatchEvent, this callback only notifies BatchEventDispatchedListeners |
| 3 | NativeAnimatedModule$animatedFrameCallback$1 |
NativeAnimatedModule.kt:353 — enqueueFrameCallback() outside the hasActiveAnimations() guard (the guard protects the work, not the re-arm) |
| 4 | FabricUIManager$DispatchUIFrameCallback |
FabricUIManager.java:1666 — finally { schedule(); } re-schedules even when all queues drained |
Runtime attribution: replacing ReactChoreographer with a logging build (log POST/RUN/REMOVE with callback class names) shows, in a 10s idle window on the stock template:
604 RUN type=NATIVE_ANIMATED_MODULE cb=com.facebook.react.animated.NativeAnimatedModule$animatedFrameCallback$1
604 RUN type=DISPATCH_UI cb=com.facebook.react.fabric.FabricUIManager$DispatchUIFrameCallback
603 POST type=NATIVE_ANIMATED_MODULE cb=com.facebook.react.animated.NativeAnimatedModule$animatedFrameCallback$1
603 POST type=DISPATCH_UI cb=com.facebook.react.fabric.FabricUIManager$DispatchUIFrameCallback
with the timers/dispatcher callbacks cycling the same way on stock builds (source-verified).
Reproduction
npx @react-native-community/cli@latest init repro --version 0.86.3 --skip-git-init
cd repro/android && ./gradlew assembleRelease
adb install -r app/build/outputs/apk/release/app-release.apk
adb shell am start -W -n com.repro/com.repro.MainActivity
# settle ≥40s, then:
adb shell atrace -t 10 -b 32768 view input -z -o /data/local/tmp/idle.atrace.gz
adb pull /data/local/tmp/idle.atrace.gz .
# → ≈600 "Choreographer#doFrame" sections for the app pid, each containing only
# an empty "animation" stage; Android 16 also exposes DoFrameCB-IsEmptyDoFrame=1
adb shell dumpsys gfxinfo com.repro reset && sleep 10 \
&& adb shell dumpsys gfxinfo com.repro | grep "Total frames rendered" # → 0Control: a raw Java Activity with setContentView(new View(this)) and zero dependencies receives 0 doFrames at idle — the OS floor is clean; this is entirely framework-driven.
Validation of the fix direction
Patched-framework experiments on the stock template (Find X8):
- Demand-gating nil #1 and
pthread.hnot found #2 (re-arm only when work exists): app fully functional, but the loop persists (pumps docs(README): fix quickstart instruction #3/Set UIStatusBarStyleLightContent #4 still active) — proving each pump independently keeps the Choreographer armed. - Gating docs(README): fix quickstart instruction #3 and Set UIStatusBarStyleLightContent #4 as well: 0 doFrames at idle, ~0% CPU, app alive and foreground — the loop fully collapses (notably, exactly one dropped re-post per pump is enough to kill each permanently: each callback was keeping only itself alive).
Proposed fix
Make each pump re-arm only when it has work, re-arming lazily from its registration path (PR to follow):
TimerFrameCallback.doFrame: re-post onlyif (timers.isNotEmpty()); re-arm fromcreateTimer.ScheduleDispatchFrameCallback.doFrame: never re-post (one-shot per schedule request).animatedFrameCallback.doFrameGuarded:enqueueFrameCallback()inside thehasActiveAnimations()branch; re-arm indidDispatchMountItemsafter operation batches execute (startAnimatingNode et al.).DispatchUIFrameCallback.doFrameGuarded: re-schedule only while mount items remain pending.
The newer subsystems (AnimationBackend, EventBeat) already follow this demand-gated pattern — these four are the legacy stragglers.
Impact
Every RN Android app, on every Android version, burns main-thread CPU at vsync rate whenever its screen is merely visible — reading, idling, screen-on standby. Worst on low-end hardware (22.5% of one core measured on a 2016 SoC) where it also competes with real frame work (15.9ms worst-case idle doFrames measured). After the fix, idle RN apps are frame-silent like native apps, with no behavior change whenever work exists.
Activity
react-native-bot commentedon Sep 6, 2026
Warning
Missing reproducer: We could not detect a reproducible example in your issue report. Reproducers are mandatory and we can accept only one of those as a valid reproducer:
You can read more about about it on our website: How to report a bug.
capt-muji commentedon Sep 7, 2026
Reproducer added per the bot's request: #58369 (RNTesterPlayground edited to render an empty
View— the framework-level loop shows with zero app code; repro commands in the PR description and in this issue's body). Fix proposal: #58368.javache commentedon Sep 7, 2026
Some prior art to investigate: we had a feature flag
enableOnDemandReactChoreographerwhich tried similar changes (#41658, #41606, #41671) and was eventually removed in #43044)capt-muji commentedon Sep 7, 2026
Thanks @javache, really useful pointers. I went through all four diffs and compared them against the four PRs linked from this issue. Here is what I found, plus one question at the end.
Why our search missed these
Our PR descriptions claim a prior-art search came up empty. These four escaped it: we searched current
mainand open PRs, but the experiment was fully reverted by February 2024, so there was nothing left onmainto find. We should have grepped release branches for the flag name too.Timeline of
enableOnDemandReactChoreographerNativeAnimatedModule: skip theNATIVE_ANIMATED_MODULEre-post whenhasActiveAnimations()is falseFabricEventDispatcher: one-shot dispatch callback, no self re-postFabricUIManager,MountItemDispatcher,FabricEventDispatcherWhat I think broke in #41606
The gate was
hasActiveAnimations(), but the only re-arm trigger that diff added wasOP_CODE_START_ANIMATING_NODEinside the Java operations loop. Anything producing animation work outside that single op-code had no way to wake the callback back up, for example:nodesManagermay report no active animationsAnimated.eventIf the internal app runs the C++ backend, the first bullet would stall or freeze animations there while OSS JS-backend apps look fine, which is consistent with "performance problems with react app". Is that close to what actually happened, or was the failure something else? This also lines up with the open question for @zeyap on #58377, and separately Reanimated parks its worklet runloop on this same slot.
How the four PRs here differ
The design rule we followed: the code path that submits work is the same code path that re-arms the callback, on every entry point.
TIMERS_EVENTScreateTimer, with a UI-thread hopNATIVE_ANIMATED_MODULEhasActiveAnimations()falseaddOperation,addUnbatchedOperation,addPreOperation, plus after each executed batchDISPATCH_UIMountItemDispatcherenqueue viaonItemsQueuedFor #58378 specifically: the old
FabricUIManager.postChoreographerCallbackIfNecessaryarmed from wrapper methods onFabricUIManager; this PR hooks the dispatcher itself, which every enqueue path must pass through, including ones that bypass those wrappers. The old code also carried a comment warning that double-scheduling could deadlock with LayoutAnimations; the single-schedule invariant is preserved through the existing idempotentschedule().Validation so far
The loop being targeted, measured stock on three device tiers at idle:
Flag-on builds of all four, backported to 0.86.3 and soaked on the 3T in foreground and background: three of the four slots fully disarmed at idle (the app keeps live timers, so
TIMERS_EVENTScorrectly stays armed), and timers, events, animations and mounts were all serviced with no starvation.Asks
capt-muji commentedon Sep 7, 2026
Self-review follow-up on the analysis above
Reading the old
FabricUIManagercondition (hasMountItems() || mDriveCxxAnimations) against currentmainexposed a real gap in one of our own PRs.The bug:
mDriveCxxAnimationstermThe fix:
onAnimationStartedfor sessions that begin while idleIn other words, reading the old experiment's code caught a live bug in our port before any reviewer had to.
Android: stop re-arming the idle DISPATCH_UI Choreographer frame call…
Android: make the batched-event-dispatch Choreographer frame callback…
YevheniiKotyrlo commentedon Oct 13, 2026
I went through the merged
disableIdleMountItemFrameCallbackRearmAndroidgate on main (95941fd). Itsfinallyblock re-arms every frame whilecxxNativeAnimatedEnabledoruseSharedAnimatedBackendis on, and theEXPERIMENTALrelease level turns both on along with the flag, so there the callback never idles.With both off, the callback idles, and these producers queue work for it without scheduling it, so the work waits for the next unrelated mount:
NativeAnimatedModulequeues them and runs them only indidDispatchMountItems, so an animation started without a commit, e.g.Animated.timing(value, {useNativeDriver: true}).start()in a handler that sets no state, does not start.enableFabricCommitBranchingMergeOnMainThread,scheduleReactRevisionMergeoff the UI thread only adds tomPendingReactRevisionMerges, so a commit from JS is neither merged nor mounted.addUIBlockandprependUIBlockonly append toInteropUIBlockListener's lists.mSynchronousEventsis cleared only at the end of a dispatch frame, so after a synchronous event whose handling queues no mount item, the next one with the same view and name (topSafeAreaInsetsChange, VirtualView'smodeChange) is dropped.maybePreallocateShadowNodequeues in C++ without waking the callback, andhasPendingItems()does not see that queue, so views are preallocated in the commit's own frame rather than while JS renders.Separately,
pause()removes the callback unconditionally, so backgrounding the app while it is idle logsTried to remove non-existent frame callback.I carry a wake for each of these in a patch on 0.86.3 and can open a PR with them against main.
perf(ui/android): stop React Native and worklets frame loops while idle
leeroybrun commentedon Nov 18, 2026
Confirming this on a production Expo SDK 55 / RN 0.83.5 app, with numbers, plus a note for anyone measuring a Reanimated app: there the four gates alone change nothing, because a fifth loop lives in
react-native-worklets.We backported #58375, #58376, #58377 and #58378 onto 0.83.5 as one unflagged patch, built ReactAndroid from source, and measured a Release arm64 build on an emulator (API 34, google_apis arm64), app idle on its home screen. All arms were built from one tree and differ only by the patch.
Choreographer#doFrame/ 10 sThe four gates are necessary but not sufficient with Reanimated
With the four gates in,
simpleperfon the idle UI thread showed over half the samples inAnimationFrameQueue.executeQueue->WorkletsModule.requestAnimationFrame, every frame. That is the loop @capt-muji flagged on #58377: worklets'setupRequestAnimationFramere-requests a native frame after every flush, whether or not anything is queued. Software Mansion is fixing it in software-mansion/react-native-reanimated#11372 (frames and mapper runs on demand, refs software-mansion/react-native-reanimated#10845), and software-mansion/react-native-reanimated#11400 (merged) stops the Android queue while the host is paused. For our numbers we used a minimal local patch on worklets 0.8.1 that requests a native frame only while a callback is queued; the reanimated PR is the complete version (it also covers mappers, finalizers and microtasks), so I'd point people there rather than at our patch.With both in place the remaining ~3.7 doFrames/s are real JS timer deadlines (next section).
Extra wakes our backport needed
Most of these match what @YevheniiKotyrlo and @saxenanickk already described, so this is mostly independent confirmation:
Handler.postDelayeduntil one frame before the earliesttargetTime, and re-arm fromcreateTimerwhen a sooner timer arrives. One detail worth keeping in whichever version lands: the disarm/sleep decision and thecreateTimercheck both run undertimerGuard, so a timer added while a frame is disarming is not lost.addOperation/addUnbatchedOperation/addPreOperation, the DISPATCH_UI callback also has to stay armed while queued batches remain, because a batch can wait up to ~3 dispatch frames in the frame-number drift logic. We added aFabricUIManager.scheduleDispatchUIFrame()for that.TrackingAnimatedNodecallsstartAnimatingNodefromNativeAnimatedNodesManager.handleEvent, outside both re-arm points of Android: stop re-arming the idle NATIVE_ANIMATED_MODULE Choreographer frame callback (behind feature flag) #58377. We added anonAnimationStartedhook on the nodes manager that arms the module's frame callback.We also hit and covered three of Yevhenii's other items: the
mSynchronousEventsdedupe set (schedule a DISPATCH_UI frame when a synchronous event is dispatched so the set clears), interopaddUIBlock/prependUIBlock, andpause()removing the callback only when it is scheduled. Since #58377 was shelved in favour of C++ Animated, items 2 and 3 only matter for apps still on the platformNativeAnimatedModule, the path our 0.83.5 build exercised.Behaviour on the patched build
Boot, a 300-row list, timer-driven relative timestamps advancing while idle (so the delayed timer wake fires), a menu open animation, list flings with an animated scroll-to-bottom button, edge swipe-back and text input all behave as before. Scroll and typing frame metrics didn't change (10 flings: 720-751 frames, 0-4 over 16 ms, input-to-frame ~20 ms average, every arm). UI-thread CPU dropped while active too: about 960-1,080 -> 700-810 ms per 22 s of scrolling, and about 700-745 -> 315-335 ms per 25 s of typing. Cold start showed no measurable difference either way. Emulator only; no device battery numbers.
Patch and repro
Gist with the 0.83.5 patch (6 files, npm package layout, no feature flags) and the measurement script: https://gist.github.com/leeroybrun/1c892c63effc0e1e7202c25a27860282.
measure-idle.sh <package>reads UI-thread CPU and context switches from/proc, then counts doFrames and UI-thread schedulings in a 10 s Perfetto trace (needsadbandtrace_processor).Side note for anyone backporting by building from source on 0.83-0.86: GitHub now serves the Hermes tarball with a
meta-hermes-<sha>top folder, and the*-stablebranches only flattenfacebook-hermes-, soconfigureBuildForHermesfails (CMake finds noCMakeLists.txt).mainalready flattens any top folder; on the stable branches, accepting both prefixes inhermes-engine/build.gradle.ktsfixes it.Happy to open the timer and NativeAnimated pieces as follow-up PRs on
mainbehind the existing flags once #58375 settles, or to fold them into Yevhenii's and saxenanickk's work rather than open parallel PRs, whichever the maintainers prefer.