Page Transitions

Goal

The default page transition system is designed to avoid visual flashes while still staying easy to replace.

It is intentionally separate from the loader so ReactWP can treat:

• first load
• critical route preparation
• route swap
• leave and enter animation

as related but distinct concerns.

Default Flow

On client-side navigation, the current flow is:

1. detect the next internal route
2. fetch the next route payload
3. ask the loader to prepare the next route and its critical assets
4. fade out the current content
5. swap the route only when the next view is ready
6. fade in the new content

Back and forward navigation use the same flow because the transition hook sits on top of the router blocker.

Main Files

• src/themes/reactwp/js/inc/PageTransition.js
• src/themes/reactwp/js/inc/config/configurePageTransition.js

Responsibilities

• PageTransition.js contains the transition runtime and its default animations
• config/configurePageTransition.js is the project-level customization point
• Loader.js is separate and owns first-load behavior and asset preloading

This means the route transition layer focuses on leave and enter, while the loader handles the initial experience.

Default Target

The shipped transition animates #viewport.

That is the shell-level container that wraps the smoother structure, which makes it a safe default for fading the whole current view in and out.

Initial Load Is Separate

The page transition runtime does not own the first-load reveal.

The first load is handled by Loader.finishInitialLoad() and the loader animation on #loader.

This distinction is important when you want:

• one animation for the initial boot
• another animation for later route changes

Customization

Use config/configurePageTransition.js to override the default route animation.

Example:

import { PageTransitionAnimation } from './PageTransition';

export const configurePageTransition = () => {

    PageTransitionAnimation
        .setLeave(({ gsap }) => {
            return gsap.to('#viewport', {
                duration: 0.2,
                opacity: 0,
                pointerEvents: 'none'
            });
        })
        .setEnter(({ gsap }) => {
            return gsap.to('#viewport', {
                duration: 0.2,
                opacity: 1,
                pointerEvents: 'initial'
            });
        });
        
};

The starter restores its default transition behavior before that configuration file runs, so a project only needs to describe its overrides.

Reduced Motion

The transition runtime also supports reduced motion handling through its immediate fallbacks.

If the user prefers reduced motion, the runtime can apply immediate state changes instead of a full tween.

Projects can provide those immediate fallbacks through the second argument of:

• PageTransitionAnimation.setLeave(animation, immediate)
• PageTransitionAnimation.setEnter(animation, immediate)