> ## Documentation Index
> Fetch the complete documentation index at: https://docs.uniwind.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Theme Transitions

> Smooth animated theme transitions powered by native snapshots

## 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.

<Info>
  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.
</Info>

<Info>
  Theme transitions are supported on iOS, Android, and Web.
</Info>

## Usage

```tsx theme={null}
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?)

<ParamField path="themeName" type="string" required>
  The name of the theme to switch to (e.g., `'light'`, `'dark'`, or a custom theme name).
</ParamField>

<ParamField path="transition" type="{ preset: ThemeTransitionPreset }">
  Optional transition configuration. If omitted, the theme changes instantly without animation.
</ParamField>

### 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      |

## 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, 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.

<Warning>
  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.
</Warning>

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

<Tip>
  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.
</Tip>

## Platform Implementation

<Tabs>
  <Tab title="iOS">
    * Uses `UIView.snapshotView(afterScreenUpdates:)` for the overlay
    * Animates with `CABasicAnimation` and `CAShapeLayer` masks
    * Overrides appearance via `window.overrideUserInterfaceStyle`
  </Tab>

  <Tab title="Android">
    * Creates a `Bitmap` snapshot via `Canvas.draw()`
    * Uses `ObjectAnimator` with `RectEvaluator` for clipping animations
    * Custom `RevealOverlay` view with `PorterDuff.Mode.CLEAR` for circle reveal
    * Overrides appearance via `AppCompatDelegate.setDefaultNightMode()`
  </Tab>

  <Tab title="Web">
    * Uses the [View Transitions API](https://developer.mozilla.org/en-US/docs/Web/API/View_Transition_API) with `::view-transition-old` and `::view-transition-new` pseudo-elements
    * Animates via CSS `clip-path` for slide and circle presets, browser default cross-fade for fade, and CSS `filter: blur()` for blur presets
  </Tab>
</Tabs>

## Important Notes

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="Fixed animation duration">
    Animation duration is fixed at 500ms with ease-in-ease-out timing on both platforms.
  </Accordion>

  <Accordion title="Future API extensions">
    Additional presets, customizable duration, and easing options are planned for future releases.
  </Accordion>
</AccordionGroup>