npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

react-native-theme-reveal

v0.1.0

Published

Animate React Native theme switches from a native window snapshot

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 prebuild

There'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 install

Quick 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>
  )
}
  • getTheme has to return the current theme synchronously. React state lags behind, so keep the theme somewhere you can read right away, like the store above.
  • setTheme has 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.
  • originFromPress reads 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 reveal when there's an origin and crossfade when 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}>
  • onPressIn takes the snapshot and keeps it off screen, so the screen stays live while the finger is down.
  • onPress calls switchTo, 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 gets onPressOut, which frees the snapshot. It does that in a later macrotask, because on release React Native calls onPressOut either before onPress in the same dispatch or, for a short press, up to 130 ms after it. A late onPressOut from an earlier press leaves the next press's snapshot alone.
  • In onPress, call switchTo before any await that waits on native work. Otherwise the deferred onPressOut can free the snapshot first, and the switch takes a new one at release as if you weren't using pressCapture. 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 later setOrigin call wins.
  • Every press-in costs a full-window snapshot, even when the touch turns into a scroll, so don't use pressCapture on 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, switchTo got 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:

  • reveal grows the shape from 24 pt tall to whatever scale covers the farthest window corner, following scale(g) = from * (to / from) ^ (g ^ 1.4) with g linear in time. inverseReveal runs the same curve backwards.
  • wipe and crossfade use 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. |

  • setTheme has to update what React renders in the same tick. Don't await anything before the update and don't wrap it in startTransition. If the update is deferred, the animation runs over the old theme and the new one appears all at once afterwards.
  • If setTheme throws, the package removes the snapshot and releases the held theme, and switchTo rejects with that error. That switch gets no onSettled call.
  • In onSettled, transition is null when no snapshot was taken (the theme switched without animating). If a snapshot was taken, transition is the type, even when native ended up showing no animation (say, Android's animator duration scale is 0).
  • capture says how the snapshot was taken: 'gpu' (API 29 and up, see How it works on Android), 'pixelcopy' (Android readback) or 'view' (iOS snapshotView). It's null when no snapshot was taken.
  • If starting the animation fails, onError runs first, then onSettled.
  • Same-theme calls get no onSettled. A call that a newer call replaced before its snapshot was taken gets no onSettled either, but one replaced mid-animation still does.
  • If onError or onSettled throws, the error goes to console.warn and 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: viewTag tells the package which window to snapshot (see Modals).
  • iOS: viewTag identifies the React root that point is measured in. Inside a pageSheet or formSheet modal that root isn't at the top of the window, so pass the tag there. Without a tag, point is 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 switchTo option, then the factory option, then the default.
  • reveal and inverseReveal need an origin, and fall back to crossfade without one.
  • If theme is already current, switchTo removes any snapshot that's on screen, frees a press-in snapshot and returns.
  • The newest switchTo call wins. An older call still waiting for its snapshot does nothing.
  • If the snapshot fails, setTheme still 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 onSettled if you need the end.
  • It only rejects if getTheme or setTheme throws.

reveal.pressCapture

{ onPressIn(event), onPressOut() } for a Pressable. See Snapshot on press-in.

  • onPressIn calls capture with the touch point (pageX, pageY) and event.nativeEvent.target. If the event has no finite touch point, it does nothing and the switch takes its snapshot at release.
  • onPressOut frees the press-in snapshot in a later macrotask, if no switchTo has used it by then. Pass it the press event (Pressable does). An onPressOut whose 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 capture replaces 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 onError and 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, not a9 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 forceDarkAllowed or, 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 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 and 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 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. 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, a TextureView or a SurfaceView, and no test compared the GPU snapshot with the screen for them. The GPU snapshot draws the views in its own HardwareRenderer. A WebView draws through a functor in that renderer, and a SurfaceView gets 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 reveal until the app process ends, once 3 reveal switches in a row have fallen back while the window stayed open. 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.

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), which originFromPress gives 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 a viewTag it 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 ImageReader in 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 HardwareRenderer and 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 with dumpsys meminfo.
  • The package frees the kept target when:
    • the app goes to the background (onTrimMemory at TRIM_MEMORY_UI_HIDDEN or 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).
  • 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 PixelCopy snapshot 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 meminfo showed 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 (onTrimMemory at TRIM_MEMORY_UI_HIDDEN or 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 Appearance and call switchTo without an origin, which gives you a crossfade. 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-animation 0.8.0.
  • skia: the Skia technique, @shopify/react-native-skia makeImageFromView with 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 tap holds 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 ours run 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 gfxinfo data alone.
  • Snapshot, JS: time from the release until JS knows the overlay is up.
  • JS max gap: longest gap between two requestAnimationFrame callbacks during the switch.
  • On React Native 0.86 (Fabric), theme-switch-animation shows 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