Skip to main content

​
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 on the native side, offering you multiple transition strategies out of the box.
Theme transitions are only available on iOS and Android. Web is not supported.

​
Usage

import { Uniwind, ThemeTransitionPreset } from 'uniwind-pro'

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

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

​
API Reference

​
setTheme(themeName, transition?)

​
themeName
string
required
The name of the theme to switch to (e.g., 'light', 'dark', or a custom theme name).
​
transition
{ preset: ThemeTransitionPreset }
Optional transition configuration. If omitted, the theme changes instantly without animation.

​
Available Presets

PresetValueDescription
ThemeTransitionPreset.None0No animation, instant theme change
ThemeTransitionPreset.Fade1Fade out animation
ThemeTransitionPreset.SlideRightToLeft2Sliding mask animation from right to left
ThemeTransitionPreset.CircleTopRight3Circular reveal expanding from top-right corner

​
How It Works

The transition animation happens in two phases:
  1. 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
  2. Animate Phase - The app switches themes while the overlay hides the change. The overlay then animates away (fading, sliding, 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.

​
Native Implementation

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

​
Important Notes

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.
Animation duration is fixed at 500ms with ease-in-ease-out timing on both platforms.
Additional presets, customizable duration, and easing options are planned for future releases.