@lemoncloud/react-page-transition

iOS/Android-style page transitions for React using the View Transitions API.

Installation

npm install @lemoncloud/react-page-transition

Peer Dependencies: react >= 18.0.0, react-router-dom >= 6.0.0

Quick Start

// 1. Import CSS (once in main.tsx)
import '@lemoncloud/page-transition-core/styles.css';

// 2. Use the hook
import { useNavigateWithTransition } from '@lemoncloud/react-page-transition';

function MyComponent() {
    const navigate = useNavigateWithTransition();

    return (
        <>
            <button onClick={() => navigate('/settings')}>Settings</button>
            <button onClick={() => navigate(-1)}>Back</button>
        </>
    );
}

API

useNavigateWithTransition(config?)

const navigate = useNavigateWithTransition({
    platform: 'auto',      // 'ios' | 'android' | 'auto'
    detectPlatform: () => 'ios' | 'android' | undefined
});

Navigation Options

navigate('/path', {
    transition: true,       // Enable animation (default: true)
    direction: 'forward',   // 'forward' | 'back'
    animation: 'slide',     // 'slide' | 'lift' | 'fade' | 'zoom' | 'none'
    replace: false          // Replace history (disables transition by default)
});

Examples

// Forward navigation
navigate('/settings');

// Back navigation
navigate(-1);

// Path with back animation
navigate('/home', { direction: 'back' });

// Modal with fade
navigate('/modal', { animation: 'fade' });

// Tab switch (no animation)
navigate('/tab', { replace: true });

// Await transition completion
await navigate('/page');
console.log('Transition complete!');

useGoBack(config?)

Convenience hook for back navigation.

import { useGoBack } from '@lemoncloud/react-page-transition';

function Header() {
    const goBack = useGoBack();
    return <button onClick={goBack}>← Back</button>;
}

Animation Types

| Type | Duration | Use Case | |------|----------|----------| | slide | 350ms | iOS default | | lift | 450ms | Android default | | fade | 350ms | Modals | | zoom | 350ms | Galleries |

Browser Support

Chrome 111+, Edge 111+, Safari 18+, Firefox 133+

Unsupported browsers fall back to instant navigation.

License

MIT © LemonCloud