react-native-theme-reveal
v0.1.0
Published
Animate React Native theme switches from a native window snapshot
Maintainers
Readme
react-native-theme-reveal
Animated theme switches for React Native, done with a native snapshot of the window: a reveal from the touch point, an inverse reveal, a wipe or a crossfade.
Right before your app applies the new theme, the package snapshots the window and lays the snapshot over your app. The theme changes underneath, then the snapshot animates away. Your components render the new theme once, and nothing has to interpolate colours per component.
- Expo module, New Architecture only. Bare React Native apps can use it through
install-expo-modules, but I haven't verified that setup. - Android 8.0+ (API 26) and iOS 16.4+.
- No runtime JS dependencies besides React, React Native and Expo.
Install
Requirements:
- Expo SDK 57 or newer (React Native 0.86 or newer), New Architecture.
- iOS: deployment target 16.4 or higher.
- Android: installs on API 24 and up, but the animation needs API 26. On API 24 and 25 the theme switches without animating.
In an Expo project:
npx expo install react-native-theme-reveal
npx expo prebuildThere's native code in here, so it won't run in Expo Go. Use a development build (npx expo run:android,
npx expo run:ios).
In a bare React Native project, set up Expo modules first (I haven't verified this setup):
npx install-expo-modules@latest
npm install react-native-theme-reveal
cd ios && pod installQuick start
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'
type Theme = 'light' | 'dark'
// getTheme has to read the theme synchronously, hence a small store outside React.
let theme: Theme = 'light'
const listeners = new Set<() => void>()
const themeStore = {
get: () => theme,
set: (next: Theme) => {
theme = next
listeners.forEach((listener) => listener())
},
subscribe: (listener: () => void) => {
listeners.add(listener)
return () => {
listeners.delete(listener)
}
},
}
// 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>
)
}getThemehas to return the current theme synchronously. React state lags behind, so keep the theme somewhere you can read right away, like the store above.setThemehas to update what React renders in the same tick, which the store above does.- Create the instance at module scope, like above. Creating it during render trips the React hooks lint rules and the React Compiler.
originFromPressreads the touch point from the press event. Presses from a keyboard, switch control or screen reader don't have one, so it measures the view you pass and uses its centre instead. That fallback is covered by unit tests, but I haven't checked a TalkBack or VoiceOver activation on a real device.- The default transition is
revealwhen there's an origin andcrossfadewhen there isn't.
The example app in example/ has every transition, a modal, the keyboard case and the benchmark screen.
Snapshot on press-in
By default switchTo takes the snapshot when the press ends. With reveal.pressCapture the package takes it when
the press starts instead, so the snapshot is ready by the release and the animation starts sooner. Spread it on the
Pressable whose onPress calls switchTo:
<Pressable ref={buttonRef} {...reveal.pressCapture} onPress={onPress}>onPressIntakes the snapshot and keeps it off screen, so the screen stays live while the finger is down.onPresscallsswitchTo, which puts the held snapshot on screen right away.- 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, because 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. - In
onPress, callswitchTobefore anyawaitthat waits on native work. Otherwise the deferredonPressOutcan free the snapshot first, and the switch takes a new one at release as if you weren't usingpressCapture.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, so don't use
pressCaptureon buttons inside a scrolling list. On Android the press-in snapshot takes the same path as a snapshot at release (see How it works on Android):- API 29 and up, the GPU snapshot: a window-size hardware bitmap (about 10 MB of GPU memory at 1080 x 2400) for as long as the snapshot is held, and 2-8 ms on the main thread. It's 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) and 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.
The catch is that the snapshot shows the screen at press-in, not at release. In pixels, that means:
- The button shows up the way it looked just before the press, with no press feedback. React Native draws the
pressed style and the ripple in a frame after
onPressIn, so the snapshot doesn't have them. At release the feedback goes away at once, hidden under the snapshot. - Without
pressCapture, the snapshot at release shows the pressed look, so 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. The snapshot is one press old.
I checked this on a Mi 11 Lite and a Pixel 8 Pro with a button that has a pressed background colour and
android_ripple, using both the PixelCopy snapshot and the GPU snapshot. The first overlay frame matched the idle
button with pressCapture and the pressed button without it, and outside the reveal hole the press-in snapshot
matched the screen at press-in pixel for pixel. The screen stays live during the hold: with a 300 ms hold, the
pressed colour and the ripple stayed visible until the release on both phones. iOS takes its snapshot the same way
(afterScreenUpdates: false), but I couldn't check the look there because the simulator can't hold a press.
If you need the exact release frame, skip pressCapture.
The switch falls back to a new snapshot at release when:
- no switch used the held snapshot within 3 s. The package then frees it, or hands it back as the kept bitmap (see Warm-up), so a long press doesn't hold on to 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 modal).
- the app went to the background,
switchTogot the current theme, or a newer press-in replaced the snapshot. - another switch started while the press-in snapshot was being taken, so the snapshot could show the screen from before that switch. That holds 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.
On Android, if the release comes before the press-in snapshot is ready, the switch waits for it and shows it. It doesn't take a second one.
iOS has the same API. There the package takes the key window's snapshotView(afterScreenUpdates: false) at
press-in and adds it to the window at release. That snapshot is cheap on iOS anyway, so the gain is small. iOS
ignores the view tag for the press-in snapshot, because it always snapshots the key window. Modals open in that
same window, so the package also compares the window's top presented view controller. If a modal was presented
during the press, or finished closing during it, the switch takes a new snapshot. A modal that's 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 it's partway through its closing animation by then.
Transitions
| | |
|---|---|
| | reveal: a hole opens in the old screen at the origin and grows to show the new theme. It's a circle, or a shape you supply. Default 450 ms. |
| | inverseReveal: the old screen stays visible only inside the shape, and the shape shrinks into the origin. This clip uses the star shape. Default 450 ms. |
| | wipe: a straight edge sweeps across the screen and uncovers the new theme. direction is the way the edge travels, so with up the edge moves up and the new theme comes in from the bottom. Defaults to up and 400 ms. |
| | crossfade: the old screen fades out. Default 300 ms. |
The clips are screen recordings of the example app (release build) on a Pixel 8 Pro, cut to 30 fps with the status bar cropped out. Click one to get the MP4.
Motion:
revealgrows the shape from 24 pt tall to whatever scale covers the farthest window corner, followingscale(g) = from * (to / from) ^ (g ^ 1.4)withglinear in time.inverseRevealruns the same curve backwards.wipeandcrossfadeuse a cubic ease in-out (0.65, 0, 0.35, 1).
API
import {
createThemeReveal,
originFromPress,
resolveTransition,
ThemeRevealModule,
} from 'react-native-theme-reveal'createThemeReveal<T>(options): ThemeReveal<T>
Create one instance per app, at module scope (outside render).
| Option | Type | Default | |
|---|---|---|---|
| getTheme | () => T | required | Returns the current theme. Must be synchronous. |
| setTheme | (theme: T) => void | required | Applies the theme. Called while the snapshot is on screen, and has to update what React renders in the same tick (see below). |
| transition | 'reveal' \| 'inverseReveal' \| 'wipe' \| 'crossfade' | reveal with an origin, else crossfade | App-wide default. |
| shape | Shape | a circle | Default shape for reveal and inverseReveal. |
| 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. |
| onError | (error: unknown) => void | console.warn | Receives native errors. The theme still applies if the snapshot fails. |
| onSettled | (info: SettledInfo) => void | none | Called when a switch finishes, with { transition, capture, prepareMs, totalMs }. |
| warmUp | boolean | true | Prepares the native snapshot path when useStart mounts. On API 29 and up that's the GPU snapshot, below that it keeps one window-size bitmap. See Warm-up. |
setThemehas to update what React renders in the same tick. Don'tawaitanything before the update and don't 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. - In
onSettled,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 (say, 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'snullwhen 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, but one replaced mid-animation still does. - If
onErrororonSettledthrows, the error goes toconsole.warnand the theme still applies.
reveal.setOrigin(point, viewTag?)
Sets the origin for the next switch only. point is in pageX / pageY space and viewTag is the tapped view.
originFromPress returns both. Call it from the press handler, before switchTo.
- Android:
viewTagtells the package which window to snapshot (see Modals). - iOS:
viewTagidentifies the React root thatpointis measured in. Inside apageSheetorformSheetmodal that root isn't at the top of the window, so pass the tag there. Without a tag,pointis treated as window points.
reveal.switchTo(theme, options?): Promise<void>
Switches to theme with an animation.
| Option | Type | |
|---|---|---|
| transition | TransitionType | This switch only. |
| shape | Shape | This switch only. |
| wipeDirection | WipeDirection | This switch only. |
- The most specific choice wins: the
switchTooption, then the factory option, then the default. revealandinverseRevealneed an origin, and fall back tocrossfadewithout one.- If
themeis already current,switchToremoves any snapshot that's 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. There's one case on Android API 29 to 33 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.
reveal.pressCapture
{ onPressIn(event), onPressOut() } for a Pressable. See Snapshot on press-in.
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.
reveal.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.
- 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.
reveal.dropCapture()
Frees the press-in snapshot. It also clears the origin that capture set, unless setOrigin set a newer one.
reveal.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). The first time it mounts, it also warms up the native side (see Warm-up).
reveal.useHeldTheme(): T | null
Hook that returns the previous theme while an animation is running, and null otherwise. Use it for anything
outside the snapshot that needs to keep the old look until the animation ends, like the system bar style:
const held = reveal.useHeldTheme()
const barTheme = held ?? theme
return <StatusBar barStyle={barTheme === 'light' ? 'dark-content' : 'light-content'} />The system bars stay live above the snapshot, so if you switch their style right away, they change before the animation has shown the new theme.
originFromPress(event, fallbackView?): Promise<PressOrigin | null>
Returns { point, viewTag } for a press event, where point is the touch point (pageX, pageY) and viewTag
is event.nativeEvent.target. If the event has no finite touch point, it measures fallbackView with
measureInWindow and returns its centre, or null if you didn't pass a fallbackView.
Call it synchronously in the press handler, before any await, and pass a view that's mounted. React Native never
calls back measureInWindow for an unmounted view, so the promise would never settle.
resolveTransition(input): Transition
Pure function that picks the transition, shape, direction and duration for a switch. switchTo uses it
internally, and it's exported for tests and custom flows.
ThemeRevealModule
The native module, with prepare(viewTag?), start(transition), cancel(), warmUp(), capture(viewTag?) and
dropCapture(). createThemeReveal calls it for you, so normally you won't need it. prepare resolves to the
CapturePath, or null when it shows no snapshot.
Types
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
}ThemeRevealOptions<T> is the options object for createThemeReveal (the table above) and ThemeReveal<T> is
what it returns. All of these types are exported.
Shape format
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 })
}path: SVG path data, filled with the nonzero rule on both platforms.anchor: the point in the shape that lands on the origin.inscribedRadius: 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, so use a value at or below the real distance. Too large a value makes the final scale too small, and whatever the shape missed snaps to the new theme at the end.- Separate the arc flags (
a9 9 0 0 1 18 0, nota9 9 0 0118 0). Android's parser can't split compact flags, although iOS reads them fine. - If the path doesn't parse, the package falls back to the circle and logs a warning naming the path. On Android, a path with compact arc flags ends up as the circle.
How it works on Android
How the package takes the snapshot depends on the API level.
On API 29 and up it draws the window's views again, on the GPU, into a hardware bitmap. No layout and no JS run for it, and elevation shadows use the same light as the window. No pixels make the trip from the GPU to the CPU and back.
On API 26 to 28 it reads the window back from the GPU with PixelCopy and then uploads it again. API 29 and up
falls back to PixelCopy too when:
- a window uses wide color mode, since 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
forceDarkAllowedor, from API 36, the system's color inversion, - the GPU snapshot fails. If no snapshot comes within 250 ms, or the GPU snapshot throws, the app sticks with
PixelCopyuntil 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 usesPixelCopyand the next one tries the GPU snapshot again. If the warm-up is still holding the thread at a later switch, that switch goes straight toPixelCopywithout 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. I haven't
measured this, since no test made the warm-up hang. On API 34 and up the PixelCopy request runs on the main
thread and doesn't wait. The package also frees each GPU snapshot's renderer on the copy thread, so if that thread
hangs, those renderers stay in memory until the process ends.
I compared the GPU snapshot with PixelCopy on a Mi 11 Lite (API 33) and a Pixel 8 Pro (API 37). On the home
screen, the benchmark screen, a screen with elevation shadows and a full-screen modal, not a single pixel differs.
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 like text under the dim or the edge of the card's shadow. The GPU blends the dim and the dialog
in one pass, while PixelCopy reads back each window and the CPU blends them, so the rounding comes out
differently. You can't see it.
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 can't go missing on screen. That's true during a press-in hold too.
- The TalkBack focus rectangle isn't 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 can't draw a hardware bitmap. - I haven't checked a
WebView, aTextureViewor aSurfaceView, 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 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 has its own difference, see
Snapshot on press-in.
Each switch reports which path it took in onSettled, as capture: 'gpu' or 'pixelcopy'.
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.
Circle reveal on the RenderThread
On API 29 and up, the default circle (reveal or inverseReveal with no shape) animates on the RenderThread with
ViewAnimationUtils.createCircularReveal, so the UI thread doesn't redraw the overlay every frame.
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's no second snapshot.- Both follow the same radius curve as the UI-thread reveal (see Transitions).
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 before it showed the live app. An animation or a video in your app won't 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.
The UI-thread reveal still runs:
- on API 26 to 28,
- when the first snapshot came from
PixelCopy(see the list above), - when the transition has a custom
shape, - for one switch, when the second snapshot doesn't come: no frame commit, no result within 200 ms of
start, a failed GPU capture, or a result for another window, size or position. The UI-thread reveal then starts at that point, with the full duration. A failed second snapshot doesn't turn the GPU snapshot off, - for one switch, when the RenderThread animator doesn't start,
- for every later
revealuntil the app process ends, once 3revealswitches in a row have fallen back while the window stayed open. Each fallback can cost a switch up to 200 ms.inverseRevealkeeps the RenderThread, because it takes no second snapshot.
wipe and crossfade always run on the UI thread.
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.
Modals
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) and the package snapshots the activity window, the dim behind the dialog and the dialog itself, then 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.
Reduce Motion and backgrounding
- 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.
- The app has to be in the foreground. If it's paused or in the background, a switch applies the theme without animating.
- If a snapshot never gets its animation start, it's removed after 1 s, so it can't get stuck on screen.
- A press-in snapshot is freed when the app goes to the background.
Warm-up
The first switch in a process used to pay for work that later switches skip. To move that out of the way, with
warmUp: true (the default) useStart() calls the native warmUp once per instance, the first time it mounts.
On Android the warm-up starts the snapshot copy thread, off the main thread, and then prepares whichever path the
activity window's first switch will take (see How it works on Android).
On API 29 and up (the GPU snapshot), 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 isn't
touched, and 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. I haven't measured what the kept target gains on its own. 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, and 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 warm-up also loads most of the package's classes on its own thread, so the first
switch doesn't load them on the main thread.
- What it gains, on the first switch in a fresh process (3 runs each): on a Pixel 8 Pro (API 37) the main thread
spent 18.2-19.0 ms on the snapshot without the warm-up and 2.9-5.7 ms with it, and the first
ImageReaderin the process accounted for 13.4-14.7 ms of that. The snapshot was ready 23.8-28.2 ms after the switch started without the warm-up and 10.3-12.9 ms with it. On a Mi 11 Lite (API 33) the first snapshot was already fast (3.9-7.1 ms on the main thread), and I couldn't measure any change from the warm-up. - What it costs: 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 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).
- The RenderThread draws your app's frames too, so 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 only matters if your app is animating right then. The benchmark can't see it, because its screen sits still after a switch.
- Memory: one window-size GPU buffer between switches, with a started
HardwareRendererand its surface. The buffer is 4 bytes per pixel, so about 10 MB at 1080x2400, and the package keeps one at most. I haven't checked it withdumpsys meminfo. - The package frees the kept target when:
- the app goes to the background (
onTrimMemoryatTRIM_MEMORY_UI_HIDDENor above). Nothing is kept until the next snapshot, and 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 then makes a new target that fits.
- the activity is destroyed.
- the GPU snapshot turns itself off.
- the module is destroyed (a JS reload).
- the app goes to the background (
- 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.
On API 26 to 28 (PixelCopy), 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. Then it copies
the window into that bitmap 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, and so does a press-in snapshot that no switch used. Inside a modal, the copy of the dialog window still allocates a new bitmap each time. - What it costs: one ARGB bitmap the size of the window, held while the app runs. At 4 bytes per pixel that's
about 10 MB at 1080x2400. 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 (measured before those phones moved to the GPU snapshot). If your app animates in its
first frames, one of them can come late. GPU memory didn't grow: on a Pixel 8 Pro,
dumpsys meminfoshowed 100 MB of Graphics with and without the kept bitmap. I haven't measured other GPUs. - 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.
If you have several instances, the warm-up runs as long as any of them has warmUp: true. With warmUp: false
there's no warm-up at all (no thread start, no GPU snapshot of nothing, no copy, no kept bitmap and no kept capture
target), and every snapshot allocates its own bitmap and its own target.
On iOS warmUp does nothing, since the snapshot there has no thread or bitmap to prepare. If the warm-up fails,
the error goes to onError and switches keep working.
Baseline Profile
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, so a Play install compiles that code ahead of time and the first switch doesn't run
it in the interpreter.
A local adb install doesn't 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
doesn't show what this profile does for a Play install.
Limits
- Android 8.0+ (API 26). Below that the theme still switches, just without animation.
- New Architecture only.
- The keyboard isn't in the snapshot. On iOS it changes theme immediately, and on Android it keeps its own theme.
- Starting a second switch mid-animation ends the first one immediately. Android shows one frame of the end state. On iOS the second snapshot captures the first animation's current frame, and the second animation starts from that.
- Android modal: tapping while the modal is still sliding in shows about 2 frames of live content on top of it.
- Android modal: with stacked modals, only the target dialog ends up in the snapshot.
- Android modal: if the dialog window is smaller than the screen, the strip outside it stays live.
- Closing a modal in the same handler that switches ("close on select"). Switch once the modal has closed.
- Android: the switch doesn't animate.
- iOS: the reveal plays over a snapshot that still shows the modal.
- To follow the system theme, listen to
Appearanceand callswitchTowithout an origin, which gives you acrossfade. The example app does this.
Testing
Under jest-expo the package's native module mock loads automatically, and switchTo applies the theme
immediately without animating.
Performance
Measured on 2026-11-08 with release builds, in two full passes (A and B). The tables below are from pass B.
Since then the code has only changed in the docs, code comments, debug log text and the module's destroy, and no
benchmark run takes a path whose behaviour those change. The method, raw dumps and scripts live in
benchmark/, and the full tables of both passes, the history and the notes are in
benchmark/RESULTS.md.
In this build, on API 29 and up, the circle reveal runs on the RenderThread from a second snapshot (see
Circle reveal on the RenderThread), so the inside of the circle is 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 a
PixelCopy snapshot, for a custom shape, and for one switch when the second snapshot fails.
Everything runs in one build of the example app, on the same screen, with a 450 ms circle reveal:
ours: 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.
| 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 |
A few things about how these were run:
- 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 doesn't 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's 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. Ours takes 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 won't look like this.
- Every
oursrun took the GPU snapshot (capture=gpu). The result files don't record a fallback to the UI-thread reveal, but debug passes with the debug log on saw none: one on the Mi 11 Lite with this build, and one on the Pixel 8 Pro with an earlier build of the same design. - Both phones drew at 60 Hz, except Skia on the Pixel 8 Pro, which drew at 30 Hz.
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 | ours | 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 | ours | 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 |
Overlay frame and snapshot JS in all four forms, ours against theme-switch-animation (ms):
| Device | Form | Overlay frame: ours | Overlay frame: theme-switch-animation | Snapshot, JS: ours | Snapshot, JS: theme-switch-animation | |---|---|---|---|---|---| | 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 |
(1) Skia drew at 30 Hz on the Pixel 8 Pro, so its frame times, janky share, late frames and missed vsyncs there can't be compared with the other two. Its missed vsyncs are counted in 33 ms intervals, so 9.5 is about 19 at 60 Hz. That's why the release rule leaves Skia out of the Pixel 8 Pro frame rows. 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.
- 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.
Release rule
On each Android device, each of our medians must be no more than 5% above the best alternative's median. That's 16 rows per form, 64 in all. Pass A passes all 64 and pass B passes 63, and the overlay frame and snapshot JS pass in every form on both phones in both passes.
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 this package caused
none of the max gaps. On the Mi, our JS max gap per 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-animation renders about 50 ms later, after its software capture has pushed the CPU
clock up. Across the four full passes of this design, our median in 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.
An earlier build of this design failed 5 cold tap rows in one of its two passes. This build keeps a capture target
between switches, and the cold tap rows pass in both passes. benchmark/RESULTS.md has
the details.
iOS (simulator)
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. I haven't measured iOS again since. There are no frame metrics, because xctrace doesn't support
hitches on the simulator and this pass has no CADisplayLink frame probe.
| Library | Snapshot, JS (ms) | JS max gap (ms) | |---|---|---| | ours | 8.3 | 16.8 | | theme-switch-animation | 11.8 | 16.9 | | skia | 44.0 | 18.0 |
The benchmark script can't tap on the simulator, so on iOS "Snapshot, JS" is measured from the run call instead of a touch.
License
MIT
