Features

• Nine transition styles. fade, circularReveal, heart, star, wipe, slide, split, pixelize, dissolve.
• Expo Go ready. Works on Expo SDK 55+ out of the box. Bare React Native CLI also supported.
• Full TypeScript inference. useTheme() and setTheme() know your theme names and color tokens without manual generics.
• System theme built in. Follows OS appearance with zero-flash startup.
• Strict runtime validation. Invalid options throw immediately with clear error messages.
• React Compiler compatible. All hooks follow the Rules of React.

Requirements

• React 19.0.0+ and React Native 0.78.0+
• @shopify/react-native-skia 2.0.0+
• react-native-reanimated 4.0.0+
• react-native-worklets 0.5.0+

Try it

• Snack Live playground with the 9 transitions. Open it on iOS — Snack's Android preview runs slowly and the animations don't render (this is a Snack limitation, not a library one; animations run fine on real Android devices and in release builds).
• Docs API reference, recipes, migration guide.

Installation

# Expo (SDK 55+)
npx expo install react-native-theme-transition @shopify/react-native-skia react-native-worklets

# React Native CLI
npm install react-native-theme-transition @shopify/react-native-skia react-native-reanimated react-native-worklets

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

Using Claude Code, Cursor, or Codex? Install the AI-assisted setup skill first and the agent can run the installation from the v2 API reference.

Quick Start

// theme.ts
import { createThemeTransition } from 'react-native-theme-transition'

export const { ThemeTransitionProvider, useTheme } = createThemeTransition({
  themes: {
    light: { background: '#ffffff', text: '#000000', primary: '#007AFF' },
    dark:  { background: '#000000', text: '#ffffff', primary: '#0A84FF' },
  },
})

// App.tsx
import { ThemeTransitionProvider } from './theme'

export default function App() {
  return (
    <ThemeTransitionProvider initialTheme="system">
      <MyApp />
    </ThemeTransitionProvider>
  )
}

// MyScreen.tsx
import { Pressable, Text, View } from 'react-native'
import { useTheme } from './theme'

function MyScreen() {
  const { theme, setTheme, isTransitioning } = useTheme()

  return (
    <View style={{ flex: 1, backgroundColor: theme.colors.background }}>
      <Text style={{ color: theme.colors.text }}>Current: {theme.name}</Text>
      <Pressable
        onPress={() => setTheme(theme.name === 'dark' ? 'light' : 'dark', { transition: 'circularReveal' })}
        disabled={isTransitioning}
      >
        <Text style={{ color: theme.colors.primary }}>Toggle</Text>
      </Pressable>
    </View>
  )
}

useTheme() returns theme, preference, setTheme, and isTransitioning. See the useTheme reference for the full API.

Want the agent to write all three files? With the AI-assisted setup skill installed, Claude Code or Cursor has these steps as a recipe and applies them to your project directly.

AI-assisted setup

For agentic coding with Claude Code, Cursor, or Codex, the library ships a skill:

npx skills add https://skills.sh/marioprieta/skills/react-native-theme-transition

It's the same content as the docs site, split into files so the agent can pull the relevant one (api, guides, recipes, examples) instead of loading everything.

Contributing

Contributions are welcome. Please read the contributing guide and open an issue first to discuss what you'd like to change.

License

MIT