react-native-theme-transition

Smooth, animated theme transitions for React Native. Captures a screenshot, overlays it, switches colors underneath, and fades out — all in JS via Reanimated. Expo Go compatible. No native code required.

Installation

Expo (SDK 54+): npx expo install react-native-theme-transition react-native-worklets

Add react-native-worklets/plugin as the last plugin in babel.config.js . On SDK 55+, do NOT add react-native-reanimated/plugin — babel-preset-expo already includes it.

Key rules

• All themes must share identical token keys — use Record<keyof typeof light, string> .

• 'system' is reserved — cannot be a theme key.

• Provider wraps everything — content outside won't be in the screenshot.

• initialTheme is read once — use a bridge component for external stores.

• setTheme during a transition returns false — use isTransitioning to disable buttons.

• onThemeChange is the only guaranteed callback — onTransitionEnd skips on capture failure.

• Don't change styles based on isTransitioning — the screenshot captures current visuals.

• No native <Switch> — use a custom toggle with useTheme({}) and plain React styles.

• No style={({ pressed }) => (...)} — use static style={{...}} .

• Selection tracking: any component whose visual state changes on theme switch must use useTheme({}) or useTheme({ initialSelection }) .

Reference guides

You need to... Read

Full API details, all options, callback ordering, exported types references/api.md

Set up a new project from scratch (Expo or CLI) references/new-project.md

Migrate from Context, Zustand, Redux, etc. references/existing-project.md

Recipes: system theme, persistence, haptics, React Navigation, Expo Router, modals, multi-theme, StatusBar, analytics references/recipes.md

Debug issues: stuck overlay, flash, type errors, system theme not working references/troubleshooting.md