Theme Transitions

Overview

Uniwind Pro provides animated theme transitions when switching between themes at runtime. The transition creates a snapshot overlay of the current screen before the theme changes, then animates that overlay away to reveal the new theme underneath.

Switching themes has never been this smooth. Uniwind Pro handles theme transitions with native snapshots on iOS and Android, and the View Transitions API on Web, offering you multiple transition strategies out of the box.

Theme transitions are supported on iOS, Android, and Web.

Usage

import { Uniwind, ThemeTransitionPreset } from 'uniwind'

// Switch theme with a transition animation
Uniwind.setTheme('dark', { preset: ThemeTransitionPreset.Fade })

// Switch theme without animation
Uniwind.setTheme('light')

Origin-based transitions

Origin presets start the animation from a point on the screen. Pass the pageX / pageY coordinates from a press event so the transition begins where the user tapped:

import { Pressable } from 'react-native'
import { Uniwind, ThemeTransitionPreset } from 'uniwind'

<Pressable
  onPress={event => {
    const { pageX, pageY } = event.nativeEvent

    Uniwind.setTheme('dark', {
      preset: ThemeTransitionPreset.CircleFromOrigin,
      origin: { x: pageX, y: pageY },
    })
  }}
/>

If origin is omitted, origin presets reveal from the screen center. Points outside the screen are clamped to its bounds.

API Reference

setTheme(themeName, transition?)

string

required

The name of the theme to switch to (e.g., 'light', 'dark', or a custom theme name).

{ preset: ThemeTransitionPreset, origin?: { x: number, y: number } }

Optional transition configuration. If omitted, the theme changes instantly without animation. origin is a screen-space point in logical pixels, matching pageX / pageY from press events, and is only used by the origin presets.

Available Presets

Preset	Value	Description
`ThemeTransitionPreset.None`	0	No animation, instant theme change
`ThemeTransitionPreset.Fade`	1	Fade out animation
`ThemeTransitionPreset.SlideRightToLeft`	2	Sliding mask animation from right to left
`ThemeTransitionPreset.SlideLeftToRight`	3	Sliding mask animation from left to right
`ThemeTransitionPreset.CircleTopRight`	4	Circular reveal expanding from top-right corner
`ThemeTransitionPreset.CircleTopLeft`	5	Circular reveal expanding from top-left corner
`ThemeTransitionPreset.CircleBottomRight`	6	Circular reveal expanding from bottom-right corner
`ThemeTransitionPreset.CircleBottomLeft`	7	Circular reveal expanding from bottom-left corner
`ThemeTransitionPreset.CircleCenter`	8	Circular reveal expanding from center
`ThemeTransitionPreset.Blur`	9	Blur out animation
`ThemeTransitionPreset.BlurRightToLeft`	10	Directional blur animation from right to left
`ThemeTransitionPreset.BlurLeftToRight`	11	Directional blur animation from left to right
`ThemeTransitionPreset.CircleFromOrigin`	12	Circular reveal expanding from the `origin` point
`ThemeTransitionPreset.SlideFromOrigin`	13	Vertical band opening left and right from `origin.x`
`ThemeTransitionPreset.BlurFromOrigin`	14	Blurred vertical band opening left and right from `origin.x`

Origin presets are available starting from Uniwind Pro 1.7.0. SlideFromOrigin and BlurFromOrigin only use origin.x, since the band grows horizontally across the full screen height.

How It Works

The transition animation happens in two phases:

Prepare Phase - When setTheme is called with a transition, the native layer captures a bitmap/snapshot of the current screen and places it as an overlay on top of the view hierarchy
Animate Phase - The app switches themes while the overlay hides the change. The overlay then animates away (fading, sliding, blurring, or revealing) to show the fully-themed new state underneath. After the animation completes, the overlay is removed from the view hierarchy

Perfect Shadow Tree Synchronization

Uniwind Pro synchronizes theme updates across the shadow tree, native components, and React re-renders, all in a single frame.

Traditional React State + ShadowTree approaches suffer from sequential rendering: React state updates, then the shadow tree updates, then native views update. This causes visible flickering or partial theme states during transitions.

Uniwind Pro achieves single-frame perfection by:

Updating the native shadow tree directly without waiting for React reconciliation
Coordinating appearance changes (light/dark mode) with style updates atomically
Using the snapshot overlay to hide any micro-delays, ensuring users see only the smooth animated reveal of the fully-themed new state

When the overlay animates away, the entire UI underneath has already been updated to the new theme. No partial states, no flickering, no “rainbow” effect of components updating at different times.

Platform Implementation

iOS
Android
Web

Uses UIView.snapshotView(afterScreenUpdates:) for the overlay
Animates with CABasicAnimation and CAShapeLayer masks
Overrides appearance via window.overrideUserInterfaceStyle

Creates a Bitmap snapshot via PixelCopy on API 26+, so hardware-rendered effects like filter: blur() are preserved, falling back to Canvas.draw() on older versions
Uses ObjectAnimator with RectEvaluator for clipping animations
Custom RevealOverlay view with PorterDuff.Mode.CLEAR for circle reveal
Overrides appearance via AppCompatDelegate.setDefaultNightMode()

Uses the View Transitions API with ::view-transition-old and ::view-transition-new pseudo-elements
Animates via CSS clip-path for slide and circle presets, a cross-fade for fade, and CSS filter: blur() for blur presets
Origin presets read the pressed point from the --uniwind-transition-origin-x and --uniwind-transition-origin-y CSS variables set on <html>

Important Notes

OS-level theme transitions are not affected

This only animates Uniwind’s in-app theme changes. The system dark/light mode transition (triggered by Control Center or Settings) happens instantly at the OS level before the app receives the notification, so users won’t see that transition regardless.

Fixed animation duration

Animation durations are fixed and use ease-in-out timing. Most presets run for 500ms. The directional and origin blur presets (BlurRightToLeft, BlurLeftToRight, BlurFromOrigin) run for about 700ms. On Web, Fade and Blur run for 750ms.On Android below API 31, blur presets fall back to a fade (Blur) or a plain wipe (directional and origin blur presets), since RenderEffect is not available.

120Hz displays

On iOS and Android devices with 120Hz displays, transitions could be skipped because the snapshot was cleaned up before the theme flip. This is fixed in Uniwind Pro 1.8.0. Upgrade if transitions don’t play on high refresh rate devices.

Future API extensions

Additional presets, customizable duration, and easing options are planned for future releases.

Releases

Features

Licensing

Theme Transitions

Overview

Usage

Origin-based transitions

API Reference

setTheme(themeName, transition?)

Available Presets

How It Works

Perfect Shadow Tree Synchronization

Platform Implementation

Important Notes

​Overview

​Usage

​Origin-based transitions

​API Reference

​setTheme(themeName, transition?)

​Available Presets

​How It Works

​Perfect Shadow Tree Synchronization

​Platform Implementation

​Important Notes

Overview

Usage

Origin-based transitions

API Reference

setTheme(themeName, transition?)

Available Presets

How It Works

Perfect Shadow Tree Synchronization

Platform Implementation

Important Notes