Forem: Mario Prieta Sánchez

How to animate theme transitions in React Native (Expo Go compatible)

Mario Prieta Sánchez — Fri, 24 Apr 2026 14:17:35 +0000

In most React Native apps, tapping a theme toggle causes the colors to flip instantly. When every detail matters and the user experience has to feel premium, that abrupt change is worth fixing.

The approach that works is to overlay a snapshot of the current view while the theme swaps underneath. Skia's makeImageFromView makes this work in Expo Go without a prebuild.

I built react-native-theme-transition to handle this pattern. The rest of this post covers installation, per-call options, integration with Expo Router, system appearance, and persistence, and closes with how the engine works.

If you use a coding agent, you can install the library's skill and the agent will handle the install, babel config, provider wrap, and sample usage.

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

Install

npx expo install react-native-theme-transition @shopify/react-native-skia react-native-worklets
Add react-native-worklets/plugin as the last plugin in babel.config.js. On Expo SDK 55+ you don't need react-native-reanimated/plugin, since babel-preset-expo already includes it.

Minimal setup

Define your themes in one file:

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

export const { ThemeTransitionProvider, useTheme } = createThemeTransition({
  themes: {
    light: { background: '#ffffff', text: '#111111', primary: '#007AFF' },
    dark:  { background: '#0b1120', text: '#f9fafb', primary: '#60a5fa' },
  },
})

Wrap your app:

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

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

Toggle the theme with one of the nine transitions:

import { useTheme } from './theme'

function MyScreen() {
  const { theme, setTheme } = useTheme()
  const next = theme.name === 'dark' ? 'light' : 'dark'

  return (
    <View style={{ backgroundColor: theme.colors.background }}>
      <Pressable onPress={() => setTheme(next, { transition: 'circularReveal' })}>
        <Text style={{ color: theme.colors.text }}>Toggle</Text>
      </Pressable>
    </View>
  )
}

That is the smallest working setup. Try it on Snack (iOS) to see all nine transitions live. For React Native CLI setups or edge-case babel configs, see the installation docs.

What you can tweak

Every setTheme call takes a transition-specific options object. Shared across all transitions: duration, easing, animated. Per transition:

circularReveal, heart, star accept origin (a view ref or {x, y}) and inverted
wipe and slide take a direction
split takes a mode and inverted
pixelize and dissolve take shader parameters
Example, using circularReveal from the tap target:

const ref = useRef<View>(null)

<Pressable
  ref={ref}
  onPress={() => setTheme(next, {
    transition: 'circularReveal',
    origin: ref,
    duration: 500,
    easing: Easing.out(Easing.cubic),
  })}
>
  <Text>Toggle</Text>
</Pressable>

TypeScript narrows the options to the fields valid for the chosen transition, so you cannot pass blockSize to fade by accident. The API reference has the full list per transition.

Wiring it up

useTheme() returns:

const { theme, preference } = useTheme()
// theme.name      → your theme keys, inferred (e.g. 'light' | 'dark' | 'ocean')
// theme.colors    → Record<Tokens, string>, typed from your themes
// theme.scheme    → 'light' | 'dark' (binary classifier)
// preference      → theme name or 'system' (the user's raw pick)

The themes object accepts any keys (e.g. light/dark, or default/sepia/night). TypeScript narrows setTheme(name, ...) to the keys you passed.

Use theme.colors for styles and theme.scheme === 'dark' wherever a binary flag is expected (React Navigation's dark prop, UI libraries like Tamagui or Gluestack).

For follow-the-OS defaults, pass systemThemeMap (mapping system light/dark to two of your theme keys) and set initialTheme="system". To persist, save preference to storage and pass it as initialTheme on next launch.

The recipes cover persistence with AsyncStorage, MMKV, and Zustand, plus React Navigation and Expo Router integrations.

How it works

Four steps run in sequence on every theme swap:

1. Capture    →  makeImageFromView() returns an SkImage of the current view
2. Overlay    →  mount the SkImage on a permanently-mounted Skia Canvas
3. Swap       →  re-render the tree underneath with the new theme tokens
4. Animate    →  fade, reveal, or shader the overlay away

The overlay hides the color swap in step 3 from the user's eye. The animation in step 4 is what the user actually perceives as the transition. The Skia Canvas stays mounted between transitions with a null image, so there's no remount flash.

The engine is ~600 lines in transitionEngine.tsx if you want to read the full implementation.

Next steps

The snapshot-overlay-swap-animate technique works beyond themes. Any time you need to animate between two full tree states (route transitions, onboarding flows, settings panels), the same approach applies.

Repo and issues: github.com/marioprieta/react-native-theme-transition
Live demo: Snack on iOS (Android Snack preview runs slow; real Android devices are fine)
Full docs: react-native-theme-transition.vercel.app

How to add Apple Game Center leaderboards to an Expo app

Mario Prieta Sánchez — Thu, 23 Apr 2026 12:28:14 +0000

I shipped my indie game Chromatch with Apple Game Center leaderboards earlier this week. My first submit got approved with the binary alone and my 6 leaderboards stayed "In Preparation" with no warning from Apple. It took a re-submit to find all the pieces that aren't obvious from the docs. Here's what ended up working, code included.

The native module

Expo doesn't ship any game center package, so you have to write a small local module with npx create-expo-module@latest --local. Here's the Swift side:

import ExpoModulesCore
import GameKit

public class ExpoGameCenterModule: Module {
  private var hasSetHandler = false

  public func definition() -> ModuleDefinition {
    Name("ExpoGameCenter")
    Events("onAuthStateChanged")

    Function("isAuthenticated") { () -> Bool in
      GKLocalPlayer.local.isAuthenticated
    }

    AsyncFunction("authenticate") { (promise: Promise) in
      if self.hasSetHandler {
        promise.resolve(GKLocalPlayer.local.isAuthenticated)
        return
      }
      self.hasSetHandler = true

      GKLocalPlayer.local.authenticateHandler = { [weak self] vc, err in
        guard let self = self else { return }
        if let vc = vc {
          DispatchQueue.main.async {
            self.rootViewController()?.present(vc, animated: true)
          }
          return
        }
        self.emitAuthState()
        promise.resolve(GKLocalPlayer.local.isAuthenticated)
      }
    }

    AsyncFunction("submitScore") { (score: Int, leaderboardID: String) in
      guard GKLocalPlayer.local.isAuthenticated else { return }
      try await GKLeaderboard.submitScore(
        score, context: 0,
        player: GKLocalPlayer.local,
        leaderboardIDs: [leaderboardID]
      )
    }

    AsyncFunction("showLeaderboards") { (leaderboardSetID: String) in
      guard GKLocalPlayer.local.isAuthenticated else { return }
      await MainActor.run {
        let gcVC: GKGameCenterViewController
        if #available(iOS 18.0, *), !leaderboardSetID.isEmpty {
          gcVC = GKGameCenterViewController(leaderboardSetID: leaderboardSetID)
        } else {
          gcVC = GKGameCenterViewController(state: .leaderboards)
        }
        gcVC.gameCenterDelegate = GameCenterDismissHandler.shared
        self.rootViewController()?.present(gcVC, animated: true)
      }
    }
  }

  private func emitAuthState() {
    self.sendEvent("onAuthStateChanged", [
      "authenticated": GKLocalPlayer.local.isAuthenticated
    ])
  }

  private func rootViewController() -> UIViewController? {
    UIApplication.shared.connectedScenes
      .compactMap { $0 as? UIWindowScene }
      .flatMap { $0.windows }
      .first { $0.isKeyWindow }?
      .rootViewController
  }
}

private class GameCenterDismissHandler: NSObject, GKGameCenterControllerDelegate {
  static let shared = GameCenterDismissHandler()
  func gameCenterViewControllerDidFinish(_ gcVC: GKGameCenterViewController) {
    gcVC.dismiss(animated: true)
  }
}

hasSetHandlerprevents reassigning Apple's handler on later calls. Reassignment is allowed but would orphan the first promise, so we set once and emit updates via events.

Events("onAuthStateChanged") with sendEvent inside the handler fills a gap in the promise flow since a second authenticate() call during pending sign-in resolves with false, and the promise won't re-fire when sign-in completes. The event will.

#available(iOS 18.0, *) is required because GKGameCenterViewController(leaderboardSetID:) is iOS 18+ only. Expo's default target is lower, so without the gate the build fails with "'init(leaderboardSetID:)' is only available in iOS 18.0 or newer". The fallback state: .leaderboards opens the generic leaderboards tab and Apple groups them under the set, so iOS 15-17 users get one extra tap.

JS bindings and hook

// modules/expo-game-center/index.ts
import { Platform } from 'react-native';
import { requireNativeModule } from 'expo-modules-core';

type AuthStateChangedEvent = { authenticated: boolean };

interface ExpoGameCenterModule {
  authenticate(): Promise<boolean>;
  submitScore(score: number, leaderboardID: string): Promise<void>;
  showLeaderboards(leaderboardSetID: string): Promise<void>;
  isAuthenticated(): boolean;
  addListener(
    eventName: 'onAuthStateChanged',
    listener: (event: AuthStateChangedEvent) => void
  ): { remove: () => void };
}

let NativeModule: ExpoGameCenterModule | null = null;
if (Platform.OS === 'ios') {
  try {
    NativeModule = requireNativeModule<ExpoGameCenterModule>('ExpoGameCenter');
  } catch { NativeModule = null; }
}

export function authenticate() {
  return NativeModule?.authenticate() ?? Promise.resolve(false);
}
export function submitScore(score: number, id: string) {
  return NativeModule?.submitScore(score, id) ?? Promise.resolve();
}
export function showLeaderboards(setID = '') {
  return NativeModule?.showLeaderboards(setID) ?? Promise.resolve();
}
export function isAuthenticated(): boolean {
  return NativeModule?.isAuthenticated() ?? false;
}
export function addAuthStateListener(
  listener: (authenticated: boolean) => void
): { remove: () => void } {
  if (!NativeModule) return { remove: () => {} };
  let last: boolean | null = null;
  return NativeModule.addListener('onAuthStateChanged', ({ authenticated }) => {
    if (authenticated === last) return;
    last = authenticated;
    listener(authenticated);
  });
}

The last variable in addAuthStateListener dedupes duplicate emits. Apple's handler sometimes fires twice with the same state, and without the guard every consumer re-renders for nothing.

// src/hooks/use-game-center.ts
import { useEffect, useState, useCallback } from 'react';
import {
  authenticate, isAuthenticated, addAuthStateListener,
  showLeaderboards as nativeShowLeaderboards,
} from '../../modules/expo-game-center';

let initialized = false;
export function initGameCenter() {
  if (initialized) return;
  initialized = true;
  authenticate();
}

export function useGameCenter(leaderboardSetID = '') {
  const [authed, setAuthed] = useState(isAuthenticated);

  useEffect(() => {
    initGameCenter();
    const sub = addAuthStateListener(setAuthed);
    setAuthed(isAuthenticated());
    return () => sub.remove();
  }, []);

  const showLeaderboard = useCallback(() => {
    if (!authed) return;
    nativeShowLeaderboards(leaderboardSetID);
  }, [authed, leaderboardSetID]);

  return { isAuthenticated: authed, showLeaderboard };
}

initGameCenter() is exported separately so you can call it once from your root layout at app startup. That triggers Apple's sign-in early, and the initialized flag prevents duplicate calls if multiple places trigger it.

Inside the hook, setAuthed(isAuthenticated()) runs right after subscribing to catch the race where Apple fires the handler between the subscribe and the initial useState read.

Config plugin for the entitlement

Game Center needs the com.apple.developer.game-center entitlement. Add it from your local module's config plugin so you don't have to touch ios/ directly.

// modules/expo-game-center/app.plugin.js
const { withEntitlementsPlist } = require('@expo/config-plugins');

module.exports = function withGameCenter(config) {
  return withEntitlementsPlist(config, (cfg) => {
    cfg.modResults['com.apple.developer.game-center'] = true;
    return cfg;
  });
};

Reference it in app.json:

"plugins": ["./modules/expo-game-center/app.plugin.js"]

App Store Connect

You can create leaderboards in the ASC web UI, or script them via the API with a .p8 key. The API has a few field names that will bite you if you're copying from old examples.

The field is defaultFormatter, not scoreFormat. The sort direction is DESC, not DESCENDING. And there's no millisecond formatter in the enum, just ELAPSED_TIME_CENTISECOND, so divide your ms by 10 before you call submitScore.

Sets are optional. Group your leaderboards into one or don't bother. The gotcha is that the moment you create your first set, every leaderboard you add after that has to sit inside a set too. So don't create one unless you actually want the grouping.

Attach components to a version submission

Creating the leaderboards in ASC isn't enough on its own. The first time you ship any Game Center component, you also have to attach it to an app version's submission so Apple reviews them together with your binary. There's no API endpoint for this. It's a manual step in the ASC web UI:

App → Game Center → click each component
"Add for Review" → "Add to an existing draft submission"
Pick the draft with your new version
Open Draft Submissions (bottom-right of the app view). Your components and the app version should all show up in the same draft.

If you miss this step Apple will approve the binary without saying a word and you'll need another version submission to ship the leaderboards.