Animated theme switches for React Native.
A native snapshot of the window, a reveal from the touch point, no Reanimated.
![]() |
![]() |
||||
Custom shape'reveal' with a star shape |
Reveal'reveal' |
||||
![]() |
![]() |
![]() |
|||
Inverse reveal'inverseReveal', star |
Wipe'wipe', up |
Crossfade'crossfade' |
|||
Release build of the example app on a Pixel 8 Pro, cut to 30 fps, status bar cropped. Click a clip for the MP4.
A native snapshot of the window covers the app while the theme changes underneath, then animates away. Components render the new theme once, so no component has to interpolate colours. The only runtime JS dependencies are React, React Native and Expo, so it needs no Reanimated and no gesture handler.
|
The window is captured natively and laid over the app. |
|
SVG path data replaces the circle for |
|
|
A switch from inside a |
With Reduce Motion or Remove animations on, the theme switches without animating. |
|
On Android API 29 and up, the snapshot draws on the GPU. The circle usually runs on the RenderThread. |
|
Under |
npx expo install react-native-theme-reveal
npx expo prebuildThis is an Expo module with native code.
- Requirements: Expo SDK 57 or newer (React Native 0.86 or newer) and the New Architecture. The legacy architecture is not supported.
- iOS: deployment target 16.4 or higher.
- Android: the package installs on API 24 and up. The animation needs API 26 (Android 8.0). On API 24 and 25 the theme switches without animating.
- Expo: Expo Go cannot load it. Use a development build (
npx expo run:android,npx expo run:ios). - Bare React Native: set up Expo modules first with
npx install-expo-modules@latest, then runnpm install react-native-theme-revealandcd ios && pod install. - Rebuild the iOS and Android apps after you install or upgrade this package. A JavaScript reload or an OTA update cannot change the native code.
See compatibility for the configurations that were tested.
import { useRef, useSyncExternalStore } from 'react'
import { Pressable, Text, View } from 'react-native'
import type { GestureResponderEvent } from 'react-native'
import { createThemeReveal, originFromPress } from 'react-native-theme-reveal'
import { themeStore, type Theme } from './theme-store'
// One instance per app, at module scope.
const reveal = createThemeReveal<Theme>({ getTheme: themeStore.get, setTheme: themeStore.set })
export default function App() {
const current = useSyncExternalStore(themeStore.subscribe, themeStore.get)
reveal.useStart() // once, near the root
const buttonRef = useRef<View>(null)
const onPress = async (event: GestureResponderEvent) => {
const origin = await originFromPress(event, buttonRef.current) // the ref is the fallback
if (origin) reveal.setOrigin(origin.point, origin.viewTag)
await reveal.switchTo(themeStore.get() === 'light' ? 'dark' : 'light')
}
return (
<View style={{ flex: 1, backgroundColor: current === 'light' ? '#fff' : '#111' }}>
<Pressable ref={buttonRef} onPress={onPress}>
<Text style={{ color: current === 'light' ? '#111' : '#fff' }}>Switch theme</Text>
</Pressable>
</View>
)
}theme-store.ts, a small store outside React
export type Theme = 'light' | 'dark'
let theme: Theme = 'light'
const listeners = new Set<() => void>()
export const themeStore = {
get: () => theme,
set: (next: Theme) => {
theme = next
listeners.forEach((listener) => listener())
},
subscribe: (listener: () => void) => {
listeners.add(listener)
return () => {
listeners.delete(listener)
}
},
}The instance needs a pair of functions:
getThememust return the current theme synchronously. React state lags behind, so keep the theme in a store that you can read right away, liketheme-store.ts.setThememust update what React renders in the same tick. The store does that.- Create the instance at module scope. An instance created during render trips the React hooks lint rules and the React Compiler.
originFromPressreads the touch point from the press event.- A press from a keyboard, switch control or screen reader has no touch point.
originFromPressthen measures the view that you pass and uses its centre. - With an origin, the default transition is
reveal. Without one, it iscrossfade.
The example app in example/ has every transition, a modal, the keyboard case and the
benchmark screen.
| Transition | What it does | Default |
|---|---|---|
reveal |
A hole opens in the old screen at the origin and grows to show the new theme. It is a circle, or a shape you supply. | 450 ms |
inverseReveal |
The old screen stays visible only inside the shape, and the shape shrinks into the origin. | 450 ms |
wipe |
A straight edge sweeps across the screen and uncovers the new theme. The direction is the way the edge travels: with up the edge moves up and the new theme comes in from the bottom. |
400 ms, up |
crossfade |
The old screen fades out. | 300 ms |
await reveal.switchTo('dark', { transition: 'wipe', wipeDirection: 'left' })revealandinverseRevealneed an origin. Without one they fall back tocrossfade.wipeandcrossfadeuse a cubic ease in-out (0.65, 0, 0.35, 1).
By default switchTo takes the snapshot when the press ends. reveal.pressCapture takes it when the
press starts, so the animation starts sooner. Spread it on the Pressable whose onPress calls
switchTo:
<Pressable ref={buttonRef} {...reveal.pressCapture} onPress={onPress}>onPressIntakes the snapshot and holds it off screen, so the screen stays live while the finger is down.onPresscallsswitchTo, which puts the held snapshot on screen right away.- In
onPress, callswitchTobefore anyawaitthat waits on native work. Otherwise the deferredonPressOutcan free the snapshot first, and the switch takes a new one at release.await originFromPress(event)is fine when the event has a touch point. - The press-in point becomes the origin for the next switch, like
setOrigin. A latersetOrigincall wins. - Every press-in costs a full-window snapshot, even when the touch turns into a scroll. Do not use
pressCaptureon buttons inside a scrolling list. - iOS has the same API. The snapshot is cheap on iOS anyway, so the gain is small.
The snapshot shows the screen at press-in, not at release:
- The button looks the way it did just before the press, with no press feedback. React Native draws
the pressed style and the ripple in a frame after
onPressIn. At release the feedback goes away at once, under the snapshot. - Without
pressCapture, the snapshot at release shows the pressed look. The old screen keeps the press feedback until the animation uncovers it. - Anything that moved during the press (a clock, a running animation, a progress bar) shows as it was at press-in.
This was checked on a Mi 11 Lite and a Pixel 8 Pro, with both Android snapshot paths and a button
that has a pressed background colour and android_ripple. The first overlay frame matched the idle
button with pressCapture and the pressed button without it. Outside the reveal hole it matched the
screen at press-in pixel for pixel. During a 300 ms hold, the pressed colour and the ripple stayed
visible until the release. iOS takes its snapshot the same way (afterScreenUpdates: false).
If you need the exact release frame, skip pressCapture.
When the switch takes a new snapshot
The switch falls back to a new snapshot at release when:
- No switch used the held snapshot within 3 s. The package frees it, or hands it back as the kept bitmap (see Warm-up on Android). A long press then does not hold a second full-window bitmap (about 10 MB at 1080 x 2400 on Android). The press-in point stays the origin.
- The window changed size, or the switch comes from another window. On Android, another window means another modal.
- The app went to the background.
switchTogot the current theme.- A newer press-in replaced the snapshot.
- Another switch started while the press-in snapshot was being taken. The snapshot could show the screen from before that switch, even when the other switch ended without an animation.
- On iOS, a modal was presented during the press, or finished closing during it.
- A switch animation was on screen at press-in. The package takes no snapshot then, since it would capture that animation's current frame.
Other details:
- On Android, if the release comes before the press-in snapshot is ready, the switch waits for it and shows it. It does not take a second one.
- A press that ends without
onPress(the finger slid off the button, or a scroll took over) only getsonPressOut, which frees the snapshot. It does that in a later macrotask. On release React Native callsonPressOuteither beforeonPressin the same dispatch or, for a short press, up to 130 ms after it. A lateonPressOutfrom an earlier press leaves the next press's snapshot alone. - On iOS the package takes the key window's
snapshotView(afterScreenUpdates: false)at press-in and adds it to the window at release. It ignores the view tag, because it always snapshots the key window. - On iOS, modals open in that same window, so the package also compares the window's top presented view controller. That is how it detects the modal case in the list above.
- On iOS, a modal that is still closing at release counts as presented, so the switch uses the press-in snapshot. That snapshot shows the modal where it was at press-in, even though the modal is partway through its closing animation by then.
A shape is SVG path data plus two numbers that position and scale it, all in path units.
const STAR: Shape = {
path:
'M50 0 L62.93 32.2 L97.55 34.55 L70.92 56.8 L79.39 90.45 L50 72 ' +
'L20.61 90.45 L29.08 56.8 L2.45 34.55 L37.07 32.2 Z',
anchor: { x: 50, y: 50 },
inscribedRadius: 21.99,
}
const onPress = async (event: GestureResponderEvent) => {
const origin = await originFromPress(event)
if (origin) reveal.setOrigin(origin.point, origin.viewTag) // a reveal with no origin falls back to crossfade
await reveal.switchTo('dark', { transition: 'reveal', shape: STAR })
}| Field | Type | Description |
|---|---|---|
path |
string |
SVG path data, filled with the nonzero rule on both platforms. |
anchor |
Point |
The point in the shape that lands on the origin. |
inscribedRadius |
number |
Distance from the anchor to the nearest edge of the shape. The package uses it to work out the scale at which the shape covers the whole window. |
- A shape applies to
revealandinverseRevealonly. - Use an
inscribedRadiusat or below the real distance. Too large a value makes the final scale too small. The parts that the shape does not cover then change to the new theme at once, at the end. - Separate the arc flags (
a9 9 0 0 1 18 0, nota9 9 0 0118 0). Android's parser cannot split compact flags, although iOS reads them fine. - If the path does not parse, the package falls back to the circle and logs a warning that names the path. On Android, a path with compact arc flags ends up as the circle.
A switch from inside a React Native <Modal> animates too.
- Android: a modal is its own dialog window. Pass the tapped view's tag
(
setOrigin(point, viewTag), whichoriginFromPressgives you). The package then snapshots the activity window, the dim behind the dialog and the dialog itself, and puts the overlay in the dialog window. Without aviewTagit uses whichever window has focus. - iOS: a modal is in the same window, so the snapshot includes it. Inside a
pageSheetorformSheetmodal, pass theviewTagtoo (seesetOrigin).
See Limits for the modal cases that do not animate fully.
| Case | Result |
|---|---|
| iOS with Reduce Motion on | The theme switches without animating. |
| Android with the animator duration scale at 0 (Remove animations) | The theme switches without animating. |
A switch while the app is paused or in the background also applies the theme without animating. The app must be in the foreground to animate.
To follow the system theme, listen to Appearance and call switchTo without an origin, which gives you a
crossfade unless the app-wide transition option is wipe. The example app does this in
useFollowSystem.ts.
The first switch in a process pays for work that later switches skip. With warmUp: true (the
default), useStart() calls the native warmUp once per instance, the first time it mounts. On
Android it prepares the snapshot path off the main thread.
- With several instances, the warm-up runs as long as any of them has
warmUp: true. - With
warmUp: falsenothing is prepared or kept. Every snapshot then allocates its own bitmap and its own capture target. - On iOS
warmUpdoes nothing, since the snapshot there has no thread or bitmap to prepare. - If the warm-up fails, the error goes to
onErrorand switches keep working.
What it gains on the first switch in a fresh process (3 runs each):
| Device | Measure | Result |
|---|---|---|
| Pixel 8 Pro (API 37) | Main thread time on the snapshot | 18.2-19.0 ms without the warm-up, 2.9-5.7 ms with it |
| Pixel 8 Pro (API 37) | Snapshot ready after the switch started | 23.8-28.2 ms without the warm-up, 10.3-12.9 ms with it |
| Mi 11 Lite (API 33) | Main thread time on the snapshot | The first snapshot was already fast (3.9-7.1 ms). No measurable change from the warm-up. |
On the Pixel 8 Pro, the first ImageReader in the process accounted for 13.4-14.7 ms of the 18.2-19.0
ms main thread time without the warm-up.
What it costs on API 29 and up (the GPU snapshot path):
| Cost | Detail |
|---|---|
| Time | 30-44 ms on the copy thread at mount on the Pixel 8 Pro and 4 ms on the Mi 11 Lite, for the 1 x 1 snapshot. Each kept capture target adds 11.5-23.8 ms on the copy thread and 4.4-18.7 ms on the RenderThread on the Mi 11 Lite (from a system trace). |
| Frames | The RenderThread draws your app's frames too. On a slow phone one app frame can come late while the package makes a target: about 0.5 s after the mount and about 0.5 s after each switch. That matters only if your app animates right then. The benchmark cannot see it, because its screen sits still after a switch. |
| Memory | One window-size GPU buffer between switches, with a started HardwareRenderer and its surface. At 4 bytes per pixel that is about 10 MB at 1080 x 2400, and the package keeps one at most. This is not verified with dumpsys meminfo. |
Warm-up on Android has the details and the PixelCopy path costs.
The Android library ships a Baseline Profile (android/src/main/baseline-prof.txt) with all of its
classes and methods in it. The Android Gradle Plugin packs it into the library's AAR and merges it
into the app's assets/dexopt/baseline.prof. A Play install then compiles that code ahead of time,
and the first switch does not run it in the interpreter.
A local adb install does not apply profiles. To get the same result as Play, add
androidx.profileinstaller 1.4.0 or later to the app (1.3.x does nothing on Android 15 and later) and
run:
adb shell am broadcast -a androidx.profileinstaller.action.INSTALL_PROFILE <package>/androidx.profileinstaller.ProfileInstallReceiver
adb shell am force-stop <package>
adb shell cmd package compile -f -m speed-profile <package>The benchmark in benchmark/ compiles all of the app's code ahead of time for every
library, so it does not show what this profile does for a Play install.
| Case | Android | iOS |
|---|---|---|
| The keyboard | Not in the snapshot. It keeps its own theme. | Not in the snapshot. It changes theme immediately. |
| A second switch mid-animation | Ends the first one immediately and shows one frame of the end state. | Ends the first one immediately. The second snapshot captures the first animation's current frame, and the second animation starts from that. |
| A modal closed in the same handler that switches ("close on select") | The switch does not animate. | The reveal plays over a snapshot that still shows the modal. |
- For "close on select", switch once the modal has closed.
- Android modals: a tap while the modal still slides in shows about 2 frames of live content on top of it. With stacked modals, only the target dialog is in the snapshot. If the dialog window is smaller than the screen, the strip outside it stays live.
- The platform requirements (New Architecture, Android 8.0 for the animation) are in Installation.
import {
createThemeReveal,
originFromPress,
resolveTransition,
ThemeRevealModule,
} from 'react-native-theme-reveal'| Function | Returns | Description |
|---|---|---|
createThemeReveal<T>(options) |
ThemeReveal<T> |
Creates the instance. Create one per app, at module scope (outside render). See Options. |
originFromPress(event, fallbackView?) |
Promise<PressOrigin | null> |
Returns { point, viewTag }: the touch point (pageX, pageY) and event.nativeEvent.target. Without a finite touch point, it measures fallbackView with measureInWindow and returns its centre. Without a fallbackView, it returns null. |
resolveTransition(input) |
Transition |
Pure function that picks the transition, shape, direction and duration for a switch. switchTo uses it internally. It is exported for tests and custom flows. |
- Call
originFromPresssynchronously in the press handler, before anyawait. - Pass a
fallbackViewthat is mounted. React Native never calls backmeasureInWindowfor an unmounted view, so the promise would never settle.
The options of createThemeReveal:
| Option | Type | Default | Description |
|---|---|---|---|
getTheme |
() => T |
required | Returns the current theme. Must be synchronous. |
setTheme |
(theme: T) => void |
required | Applies the theme. It runs while the snapshot is on screen, and must update what React renders in the same tick. |
transition |
'reveal' | 'inverseReveal' | 'wipe' | 'crossfade' |
'reveal' with an origin, else 'crossfade' |
App-wide default. |
shape |
Shape |
a circle | Default shape for reveal and inverseReveal. See Shapes. |
wipeDirection |
'up' | 'down' | 'left' | 'right' |
'up' |
Default direction for wipe. |
durations |
Partial<Record<TransitionType, number>> |
450 / 450 / 400 / 300 ms |
Per transition type, in ms. Anything non-finite, 0 or below, or over 10 000 falls back to the default. |
warmUp |
boolean |
true |
Prepares the native snapshot path when useStart mounts. On API 29 and up that is the GPU snapshot. Below that it keeps one window-size bitmap. See Warm-up. |
The options onError and onSettled are in Callbacks.
- Do not
awaitanything before the update insetTheme, and do not wrap it instartTransition. If the update is deferred, the animation runs over the old theme and the new one appears all at once afterwards. - If
setThemethrows, the package removes the snapshot and releases the held theme, andswitchTorejects with that error. That switch gets noonSettledcall.
| Callback | Type | Default | When |
|---|---|---|---|
onSettled |
(info: SettledInfo) => void |
- | A switch finishes. info is { transition, capture, prepareMs, totalMs }. |
onError |
(error: unknown) => void |
console.warn |
A native call fails. The theme still applies if the snapshot fails. |
transitionisnullwhen no snapshot was taken (the theme switched without animating). If a snapshot was taken,transitionis the type, even when native ended up showing no animation (for example, when Android's animator duration scale is 0).capturesays how the snapshot was taken:'gpu'(API 29 and up, see How it works on Android),'pixelcopy'(Android readback) or'view'(iOSsnapshotView). It isnullwhen no snapshot was taken.- If starting the animation fails,
onErrorruns first, thenonSettled. - Same-theme calls get no
onSettled. A call that a newer call replaced before its snapshot was taken gets noonSettledeither. A call replaced mid-animation still does. - If
onErrororonSettledthrows, the error goes toconsole.warnand the theme still applies.
The methods of the ThemeReveal<T> instance:
| Method | Description |
|---|---|
setOrigin(point, viewTag?) |
Sets the origin for the next switch only. Call it from the press handler, before switchTo. point is in pageX / pageY space and viewTag is the tapped view. originFromPress returns both. |
switchTo(theme, options?) |
Switches to theme with an animation. options can set transition, shape and wipeDirection for this switch only. Returns Promise<void>. |
pressCapture |
{ onPressIn(event), onPressOut(event?) } for a Pressable. See Snapshot on press-in. |
capture(point, viewTag?) |
Takes the snapshot now and keeps it off screen for the next switchTo. It also sets point and viewTag as the origin for the next switch, like setOrigin. |
dropCapture() |
Frees the press-in snapshot. It also clears the origin that capture set, unless setOrigin set a newer one. |
useStart() |
Hook that starts the animation once React has committed the new theme. Mount it once, in a component that re-renders when the theme changes (the root is a good spot). Its first mount also runs the warm-up. |
useHeldTheme() |
Hook that returns the previous theme (T) while an animation runs, and null otherwise. |
The viewTag of setOrigin:
- Android:
viewTagtells the package which window to snapshot (see Modals). - iOS:
viewTagidentifies the React root thatpointis measured in. Inside apageSheetorformSheetmodal that root is not at the top of the window, so pass the tag there. Without a tag,pointis treated as window points.
switchTo:
- The most specific choice wins: the
switchTooption, then the factory option, then the default. - If
themeis already current,switchToremoves any snapshot that is on screen, frees a press-in snapshot and returns. - The newest
switchTocall wins. An older call still waiting for its snapshot does nothing. - If the snapshot fails,
setThemestill runs without animation. On Android API 29 to 33 there is one case where it waits instead, see How it works on Android. - The promise resolves once the theme is set, before the animation ends. Use
onSettledif you need the end. - It only rejects if
getThemeorsetThemethrows.
pressCapture and capture:
onPressIncallscapturewith the touch point (pageX,pageY) andevent.nativeEvent.target. If the event has no finite touch point, it does nothing and the switch takes its snapshot at release.onPressOutfrees the press-in snapshot in a later macrotask, if noswitchTohas used it by then. Pass it the press event (Pressabledoes). AnonPressOutwhose touch is older than the snapshot's press-in is ignored.- A second
capturereplaces the first. - If no switch uses the snapshot within 3 s, the package frees it. The point stays the origin until the press ends.
- If the native capture fails, the error goes to
onErrorand the next switch takes its snapshot as usual.
useHeldTheme keeps anything outside the snapshot on the old look until the animation ends, like the
system bar style. The system bars stay live above the snapshot. If you switch their style right away,
they change before the animation has shown the new theme.
const held = reveal.useHeldTheme()
const barTheme = held ?? theme
return <StatusBar barStyle={barTheme === 'light' ? 'dark-content' : 'light-content'} />ThemeRevealModule, the native module
createThemeReveal calls it for you, so normally you do not need it.
| Method | Returns | Description |
|---|---|---|
prepare(viewTag?) |
Promise<CapturePath | null> |
Takes the snapshot. Resolves to the CapturePath, or null when it shows no snapshot. |
start(transition) |
Promise<void> |
Starts the animation. |
cancel() |
Promise<void> |
Removes the snapshot. |
warmUp() |
Promise<void> |
Runs the warm-up. |
capture(viewTag?) |
Promise<boolean> |
Takes a press-in snapshot. |
dropCapture() |
Promise<void> |
Frees the press-in snapshot. |
import type {
ThemeRevealOptions, // the options of createThemeReveal
ThemeReveal, // the instance that createThemeReveal returns
Point, // { x: number; y: number }
Shape, // { path: string; anchor: Point; inscribedRadius: number }
WipeDirection, // 'up' | 'down' | 'left' | 'right'
Transition, // a resolved transition, see below
TransitionType, // 'reveal' | 'inverseReveal' | 'wipe' | 'crossfade'
CapturePath, // 'gpu' | 'pixelcopy' | 'view'
SettledInfo, // what onSettled gets
SwitchOptions, // the options of switchTo
PressOrigin, // what originFromPress returns
PressCapture, // the type of pressCapture
} from 'react-native-theme-reveal'MeasurableView (the fallbackView of originFromPress) and ResolveTransitionInput (the input of
resolveTransition) are exported too.
Full type definitions
type Point = { x: number; y: number }
type Shape = { path: string; anchor: Point; inscribedRadius: number }
type WipeDirection = 'up' | 'down' | 'left' | 'right'
type Transition =
| { type: 'reveal'; origin: Point; durationMs: number; shape?: Shape }
| { type: 'inverseReveal'; origin: Point; durationMs: number; shape?: Shape }
| { type: 'wipe'; direction: WipeDirection; durationMs: number }
| { type: 'crossfade'; durationMs: number }
type TransitionType = Transition['type']
type CapturePath = 'gpu' | 'pixelcopy' | 'view'
type SettledInfo = {
transition: TransitionType | null
capture: CapturePath | null
prepareMs: number
totalMs: number
}
type SwitchOptions = { transition?: TransitionType; shape?: Shape; wipeDirection?: WipeDirection }
type PressOrigin = { point: Point; viewTag?: number }
type PressCapture = { onPressIn(event: GestureResponderEvent): void; onPressOut(event?: GestureResponderEvent): void }
type MeasurableView = {
measureInWindow(callback: (x: number, y: number, width: number, height: number) => void): void
}
type ResolveTransitionInput = {
requested?: TransitionType // the switchTo option
fallback?: TransitionType // the factory option
origin: Point | null
shape?: Shape
durations?: Partial<Record<TransitionType, number>>
wipeDirection?: WipeDirection
requestedShape?: Shape
requestedWipeDirection?: WipeDirection
}Under jest-expo the package's native module mock loads automatically. No setup is needed.
await reveal.switchTo('dark') // setTheme runs at once, no animation- The mock ships in the package as
mocks/ThemeReveal.js. prepareresolvesnull, soswitchToapplies the theme immediately without animating.onSettledthen getstransition: nullandcapture: null.captureresolvesfalse.start,cancel,warmUpanddropCaptureresolve with no value.
| Tested with | |
|---|---|
| Expo / React Native / React | Expo SDK 57, React Native 0.86.3, React 19.2.3 |
| Architecture | New Architecture |
| iOS | iOS 26.5 simulator |
| Android | Xiaomi Mi 11 Lite (Android 13, API 33), Pixel 8 Pro (Android 17, API 37) |
The package requires the New Architecture. The peer ranges (expo >=57.0.0, react-native >=0.86.0,
react *) and the minimum targets (iOS 16.4, Android API 24) are what the package declares. They are
not a tested matrix.
These setups are not verified:
- Bare React Native through
install-expo-modules. - A TalkBack or VoiceOver activation with
originFromPresson a real device. Unit tests cover the fallback to the view centre. - The look of the press-in snapshot on iOS. The simulator cannot hold a press.
- A
WebView, aTextureViewor aSurfaceViewin the GPU snapshot (see How it works on Android).
Measured on 2026-11-08 with release builds, in two full passes (A and B). The tables show pass B.
Every library runs in one build of the example app, on the same screen, with a 450 ms circle reveal.
The method, raw dumps and scripts are in benchmark/. The full tables of both passes,
the history and the notes are in benchmark/RESULTS.md.
react-native-theme-reveal: this package.theme-switch-animation:react-native-theme-switch-animation0.8.0.skia: the Skia technique,@shopify/react-native-skiamakeImageFromViewwith a circle mask animated by Reanimated.
Warm, input tap (median of 6). Lower is better in every column.
| Device | Library | Overlay frame (ms) | Snapshot, JS (ms) | Frame p50 (ms) | Frame p90 (ms) | Janky (%) | Late frames | Missed vsyncs | JS max gap (ms) |
|---|---|---|---|---|---|---|---|---|---|
| Mi 11 Lite | react-native-theme-reveal | 57.4 | 47.2 | 15.3 | 20.6 | 38 | 0 | 2 | 43.0 |
| Mi 11 Lite | theme-switch-animation | 88.7 | 73.2 | 17.7 | 24.0 | 67 | 0.5 | 3.5 | 45.0 |
| Mi 11 Lite | skia | 431.9 | 414.0 | 18.9 | 22.8 | 67 | 0 | 25 | 391.1 |
| Pixel 8 Pro | react-native-theme-reveal | 49.4 | 45.9 | 7.7 | 9.3 | 0 | 0 | 2 | 25.4 |
| Pixel 8 Pro | theme-switch-animation | 64.9 | 66.2 | 8.2 | 9.5 | 3 | 0 | 3 | 32.2 |
| Pixel 8 Pro | skia | 330.8 | 291.4 | 6.9 (1) | 8.9 (1) | 0 (1) | 0 (1) | 9.5 (1) | 267.9 |
(1) Skia drew at 30 Hz on the Pixel 8 Pro, so its frame times, janky share, late frames and missed vsyncs there cannot be compared with the other two. Its missed vsyncs are counted in 33 ms intervals, so 9.5 is about 19 at 60 Hz.
- Overlay frame: time from the release to the first frame with the overlay on screen. On the Mi 11
Lite a system trace confirmed which frame that is. On the Pixel 8 Pro it rests on
gfxinfodata alone. - Snapshot, JS: time from the release until JS knows the overlay is up.
- JS max gap: longest gap between two
requestAnimationFramecallbacks during the switch. - On React Native 0.86 (Fabric),
theme-switch-animationshows no visible circle. It reveals the old screen over the old screen, and the new theme appears all at once at the end. Its timings are still real. - On API 29 and up, the circle of
react-native-theme-revealruns on the RenderThread over a still image of the new screen (see Circle reveal on the RenderThread).
Full benchmark results
| Device | OS | Build | Runs per library |
|---|---|---|---|
Xiaomi Mi 11 Lite (M2101K9AG) |
Android 13 (API 33) | release, arm64-v8a, compiled with speed |
warm: 1 warm-up + 6 interleaved rounds. Cold: 3 rounds |
| Pixel 8 Pro | Android 17 (API 37) | release, arm64-v8a, compiled with speed |
warm: 1 warm-up + 6 interleaved rounds. Cold: 3 rounds |
Overlay frame and snapshot JS in all four forms, react-native-theme-reveal (RNTR) against
theme-switch-animation (TSA), in ms:
| Device | Form | Overlay frame: RNTR | Overlay frame: TSA | Snapshot, JS: RNTR | Snapshot, JS: TSA |
|---|---|---|---|---|---|
| Mi 11 Lite | Warm tap | 57.4 | 88.7 | 47.2 | 73.2 |
| Mi 11 Lite | Warm hold | 41.0 | 94.2 | 31.6 | 80.2 |
| Mi 11 Lite | Cold tap | 65.5 | 88.0 | 58.0 | 84.1 |
| Mi 11 Lite | Cold hold | 43.0 | 107.7 | 33.9 | 67.6 |
| Pixel 8 Pro | Warm tap | 49.4 | 64.9 | 45.9 | 66.2 |
| Pixel 8 Pro | Warm hold | 39.1 | 64.5 | 31.7 | 64.0 |
| Pixel 8 Pro | Cold tap | 53.8 | 89.5 | 47.5 | 87.6 |
| Pixel 8 Pro | Cold hold | 39.1 | 102.2 | 32.2 | 65.3 |
- Before each pass the benchmark compiles the whole app ahead of time
(
cmd package compile -f -m speed), so all three libraries run compiled code. That means it does not show what the Baseline Profile does for a Play install. - Each pass runs with two kinds of tap, the same for every library.
input tapholds the press for about 0 ms, which no finger does, so there is also a hold form that presses for 100 ms (input swipe x y x y 100). The clock starts at the release (onPress) in both.react-native-theme-revealtakes its snapshot on press-in (Snapshot on press-in), so the hold form is closer to what a finger gets. - Cold means the first switch in a fresh process: the app is force-stopped 1 s before each run. The screen mounts about 1.5 s before the tap, so the warm-up has finished by then. If your app's first switch comes sooner, it will not look like this.
- Every
react-native-theme-revealrun took the GPU snapshot (capture=gpu). The result files do not record a fallback to the UI-thread reveal. Debug passes with the debug log on saw none: one on the Mi 11 Lite with the measured build, and one on the Pixel 8 Pro with an earlier build of the same design. - The circle reveal of
react-native-theme-revealruns on the RenderThread from a second snapshot on API 29 and up. The inside of the circle is then a still image of the new screen for the reveal's 450 ms. The UI-thread reveal still runs on API 26 to 28, for aPixelCopysnapshot, for a custom shape, and for one switch when the second snapshot fails. - Both phones drew at 60 Hz, except Skia on the Pixel 8 Pro, which drew at 30 Hz.
On each Android device, each median of react-native-theme-reveal must be no more than 5% above the
best alternative's median. That is 16 rows per form, 64 in all. Pass A passes all 64 and pass B passes
63. The overlay frame and snapshot JS pass in every form on both phones in both passes.
The rule leaves Skia out of the Pixel 8 Pro frame rows, because Skia drew at 30 Hz there. With Skia in them, 7 more rows would fail in pass B: frame p50 in all four forms, frame p90 in cold tap, and janky share in cold tap and cold hold.
The one row that fails is the Mi 11 Lite JS max gap in pass B's warm hold: 44.1 ms vs 39.7 ms for
theme-switch-animation (limit 41.7 ms). A system trace of 6 runs on the same build shows that this
package caused none of the max gaps:
- On the Mi, the JS max gap of
react-native-theme-revealper run is either fast (25.4-31.8 ms) or slow (41.8-51.2 ms) in 22 of 24 runs. - In a slow run the system kept the app on the little CPU cores, and the app's own JS theme render took 46-53 ms there.
theme-switch-animationrenders about 50 ms later, after its software capture has pushed the CPU clock up.- Across the four full passes of this design, the median of
react-native-theme-revealin this row was 35.0, 34.8, 37.8 and 44.1 ms, against 42.2, 39.4, 39.8 and 39.7 ms. - The only levers are a CPU boost and a later theme render. A boost games the metric and a later render makes the switch slower, so the package does neither.
These numbers are from the iOS 26.5 simulator on a Mac, not a phone, measured on 2026-10-28 before
the press-in snapshot existed. iOS is not measured again since. There are no frame metrics, because
xctrace does not support hitches on the simulator and this pass has no CADisplayLink frame probe.
| Library | Snapshot, JS (ms) | JS max gap (ms) |
|---|---|---|
| react-native-theme-reveal | 8.3 | 16.8 |
| theme-switch-animation | 11.8 | 16.9 |
| skia | 44.0 | 18.0 |
The benchmark script cannot tap on the simulator, so on iOS "Snapshot, JS" is measured from the run call instead of a touch.
switchTo asks the native module to snapshot the window and lay the snapshot over the app as an
overlay. Then it calls setTheme, and React renders the new theme under the overlay. Once React has
committed, useStart starts the animation, and the overlay uncovers the new screen. On iOS the
snapshot is the key window's snapshotView. On Android it is a GPU snapshot or a PixelCopy readback,
and the overlay lives in the window's ViewOverlay.
revealgrows the shape from 24 pt tall to the scale that covers the farthest window corner. It followsscale(g) = from * (to / from) ^ (g ^ 1.4), withglinear in time.inverseRevealruns the same curve backwards.- A snapshot that never gets its animation start is removed after 1 s, so it cannot get stuck on screen.
- If the app goes to the background while a press-in snapshot is held, the package frees that snapshot.
On API 29 and up the package draws the window's views again, on the GPU, into a hardware bitmap. On
API 26 to 28, and in a few cases on API 29 and up, it reads the window back with PixelCopy. Each
switch reports which path it took in onSettled, as capture: 'gpu' or 'pixelcopy'.
Android snapshot paths
The GPU snapshot runs no layout and no JS, and elevation shadows use the same light as the window. No
pixels make the trip from the GPU to the CPU and back. The PixelCopy path reads the window back from
the GPU and then uploads it again. API 29 and up falls back to PixelCopy in these cases:
| Trigger | Why |
|---|---|
| A window uses wide color mode | The GPU snapshot is sRGB. |
| A window has no hardware acceleration | |
The theme has no light values for shadows (lightY, lightZ, lightRadius, ambientShadowAlpha, spotShadowAlpha) |
|
| A view change is waiting for its frame while force dark can apply | A light theme in night mode, with forceDarkAllowed or, from API 36, the system's color inversion. |
| The GPU snapshot fails | See below. |
If no GPU snapshot comes within 250 ms, or the GPU snapshot throws, the app sticks with PixelCopy
until its process ends. The exception is a slow warm-up: if the 250 ms run out while the warm-up still
holds the copy thread, only that switch uses PixelCopy. The next one tries the GPU snapshot again.
If the warm-up still holds the thread at a later switch, that switch goes straight to PixelCopy
without waiting the 250 ms.
A warm-up that never ends is a problem on API 29 to 33, because there the PixelCopy request runs on
the copy thread too. The PixelCopy snapshot then waits behind the warm-up, and so do the switch and
setTheme. This is not measured, since no test made the warm-up hang. On API 34 and up the
PixelCopy request runs on the main thread and does not wait. The package also frees each GPU
snapshot's renderer on the copy thread. If that thread hangs, those renderers stay in memory until the
process ends.
Compared with PixelCopy on a Mi 11 Lite (API 33) and a Pixel 8 Pro (API 37), the GPU snapshot
matched pixel for pixel on the home screen, the benchmark screen, a screen with elevation shadows and
a full-screen modal. With a transparent modal and a dim, 0.6% to 0.7% of the pixels differ by 1 or 2
out of 255 in a channel, at translucent edges, because the GPU and the CPU blend the dim and the
dialog with different rounding. The difference is not visible.
The PixelCopy snapshot matches the screen exactly for the activity window. Under a transparent
modal's dim on a Pixel 8 Pro, 186 single pixels at text edges were off by up to 5 out of 255 in a
channel (2%), from the CPU blend of the dim and the dialog. The press-in snapshot shows the screen at
press-in (see What the snapshot shows).
The GPU snapshot has a few other quirks:
- A view that changed since the window's last frame draws again first, so the snapshot can show the change one frame before the screen does. Any window with such a change then redraws in full, so the change cannot go missing on screen. That is true during a press-in hold too.
- The TalkBack focus rectangle is not in it, because the window draws that rectangle outside its views.
- A screenshot that draws the window into a software canvas (
View.draw) while the overlay is up leaves the overlay out, because a software canvas cannot draw a hardware bitmap. - A
WebView, aTextureViewand aSurfaceVieware not verified, and no test compared the GPU snapshot with the screen for them. The GPU snapshot draws the views in its ownHardwareRenderer. AWebViewdraws through a functor in that renderer, and aSurfaceViewgets that renderer's frame number for its position. If your app shows one of these, compare a snapshot with the screen.
The press-in snapshot takes the same path as a snapshot at release:
| Android | Snapshot | Memory while held | Time |
|---|---|---|---|
| API 29 and up | GPU snapshot | A window-size hardware bitmap, about 10 MB of GPU memory at 1080 x 2400 | 2-8 ms on the main thread. Ready 10-30 ms after the capture starts on a Mi 11 Lite and a Pixel 8 Pro. |
| API 26 to 28 | PixelCopy |
A window-size bitmap, about 10 MB | 25-47 ms of GPU readback on a Mi 11 Lite. The bitmap is the one the warm-up keeps, and it goes back there if no switch uses the snapshot. |
During a press-in hold on API 29 and up, the package also draws the held GPU snapshot once, scaled down, into a small offscreen target. That moves the upload of its texture out of the overlay's first frame.
The overlay lives in the ViewOverlay of the window's root view, in the activity window or, for a
switch from a modal, the dialog window. It draws above every view of that window, including any view
the app or the system adds during the animation. It takes no touches and is hidden from
accessibility.
The warm-up starts the snapshot copy thread, off the main thread. Then it prepares whichever path the activity window's first switch will take. It also loads most of the package's classes on its own thread, so the first switch does not load them on the main thread.
Warm-up internals
With warmUp: false there is no thread start, no GPU snapshot of nothing, no copy, no kept bitmap
and no kept capture target.
GPU snapshot path (API 29 and up). The warm-up makes a 1 x 1 GPU snapshot of nothing on the copy
thread: an ImageReader, a HardwareRenderer and one drawn frame, which it then frees. It draws no
view, so the window is not touched. It keeps no bitmap, because each GPU snapshot makes its own
hardware bitmap and frees it with the snapshot. A switch that falls back to PixelCopy keeps its
bitmap, the same as on API 26 to 28.
Then, 500 ms after the mount and once the main thread is next idle, it makes one capture target the
size of the activity window on the copy thread: an ImageReader, a HardwareRenderer with its
surface, and one allocated buffer. It holds on to that target until a snapshot of the activity window
uses it, so that snapshot skips the setup. What the kept target gains on its own is not measured.
- The package makes the next target the same way, 500 ms after a switch ends or after a press-in snapshot that no switch used.
- It waits while an overlay shows, a snapshot runs or a press-in snapshot is held. It tries again when the activity comes back to the foreground.
- A switch that starts while a target is being made waits for it. Its snapshot gets its image after that work ends, 11.5-23.8 ms on a Mi 11 Lite.
The package frees the kept target when:
| Trigger | What happens next |
|---|---|
The app goes to the background (onTrimMemory at TRIM_MEMORY_UI_HIDDEN or above) |
Nothing is kept until the next snapshot. The package keeps a new target after that switch. |
| The system is low on memory | |
| The screen size changes | |
| At the next prepare, the activity window has a different size or its snapshot no longer takes the GPU path | If the GPU path is on, the package makes a new target that fits. |
| The activity is destroyed | |
| The GPU snapshot turns itself off | |
| The module is destroyed (a JS reload) |
A snapshot of a window with a different size frees the target and makes its own. The free runs on the copy thread before that snapshot's image gets there, so the image can end up waiting for it.
PixelCopy path (API 26 to 28). The warm-up takes this path on API 26 to 28. It also takes it for
an API 29+ activity window that takes PixelCopy (see
How it works on Android), and in a process where the GPU snapshot switched
itself off before the warm-up ran. The warm-up allocates one bitmap the size of the window on the
copy thread, copies the window into it once and keeps it. The first copy into a fresh bitmap is the
slow one, so this way the first switch gets a fast copy.
- Every
PixelCopysnapshot copies into the kept bitmap and gets it back when the snapshot goes away. A press-in snapshot that no switch used gives it back too. Inside a modal, the copy of the dialog window still allocates a new bitmap each time. - Memory: one ARGB bitmap the size of the window, held while the app runs. At 4 bytes per pixel that
is about 10 MB at 1080 x 2400. GPU memory did not grow: on a Pixel 8 Pro,
dumpsys meminfoshowed 100 MB of Graphics with and without the kept bitmap. Other GPUs are not measured. - Time: the one copy at mount takes the RenderThread once, for 16-26 ms on a Mi 11 Lite and 39-60 ms on a Pixel 8 Pro. These numbers were measured before those phones moved to the GPU snapshot. If your app animates in its first frames, one of them can come late.
- The bitmap is freed when the app goes to the background (
onTrimMemoryatTRIM_MEMORY_UI_HIDDENor above), on low memory, when the screen size changes and when the activity is destroyed. Nothing is kept while the app is in the background, and the next switch keeps a new bitmap.
On API 29 and up, the default circle (reveal or inverseReveal with no shape) usually animates on
the RenderThread with ViewAnimationUtils.createCircularReveal. The UI thread then does not redraw
the overlay every frame. For reveal, this changes what you see:
- Inside the circle you get a still image of the new screen for the length of the reveal, where the UI-thread reveal shows the live app. An animation or a video in your app does not move inside the circle until the reveal ends.
- The circle starts 2 to 3 frames after
start, once the second snapshot is in. The reveal keeps its duration, so it also ends that much later.
How it runs and when it falls back
reveal: the overlay holds still while the next frame draws the new theme. In the frame after that, the package takes a second GPU snapshot of the same window or windows, this time without the overlay. That second snapshot goes on top of the first, and a circular clip on it grows from the origin.inverseReveal: a circular clip on the first snapshot shrinks into the origin. There is no second snapshot.- Both follow the same radius curve as the UI-thread reveal (see How it works).
The UI-thread reveal still runs in these cases:
| Case | Scope |
|---|---|
| API 26 to 28 | Every switch |
The first snapshot came from PixelCopy (see Android snapshot paths) |
That switch |
The transition has a custom shape |
That switch |
The second snapshot does not come: no frame commit, no result within 200 ms of start, a failed GPU capture, or a result for another window, size or position |
One switch. The UI-thread reveal then starts at that point, with the full duration. A failed second snapshot does not turn the GPU snapshot off. |
| The RenderThread animator does not start | One switch |
3 reveal switches in a row fell back while the window stayed open |
Every later reveal until the app process ends. Each fallback can cost a switch up to 200 ms. inverseReveal keeps the RenderThread, because it takes no second snapshot. |
wipe and crossfade always run on the UI thread.
Try changes in the example/ app. The benchmark method and scripts are in
benchmark/README.md.
npx jest --ci # Jest, one run (npm test starts watch mode in a terminal)
bash scripts/test-ios-parser.sh # iOS SVG path parser and motion tests, no simulator
python3 -m unittest discover -s benchmark # benchmark script tests



