React Motion Router

Declarative routing library for React ⚛ with 60FPS page transitions and animations 🚀. Out of the box support for Shared Element Transitions 🤩. Under Development 🧪. Based on React Router and React Navigation.

Demo

Table of Contents

• Installation
• Usage
  • Basic
  • Navigation
  • Passing Params
  • Default Params
  • Transitions
  • Shared Element Transition
• API Documentation
  • Stack.Screen
  • Stack.Screen Config
  • Router Config
  • AnimationConfig
  • SharedElement
  • SharedElement Config
• Remarks
• Credits

Installation

npm install react-motion-router

Usage

Basic

Use the Router component to render your screens. Pass a React component to the component prop of Stack.Screen to be rendered when the path prop of the screen has been navigated to.

// ...
import {Router, Stack} from 'react-motion-router';

function Home() {
    return(
        <div className="Home">
            <h1>Hello World</h1>
        </div>
    );
}
function App() {
    return(
        <div className="app">
            <Router>
                <Stack.Screen path="/" component={Home} />
            </Router>
        </div>
    ):
}

// ...

You can also pass lazy loaded components to the screen along with an optional fallback component to be rendered while your component loads.

// ...
const Home = React.lazy(() => import('./Screens/Home'));
<Router>
    <Stack.Screen path="/" component={Home} fallback={<div className='screen-fallback home'></div>}>
</Router>
// ...

If a fallback component is provided the fallback component is animated in just like the actual component would and is even able to do gesture navigation all while your screen is loaded in asynchronously.

Navigation

Navigation is done through the navigation object exposed on your screen's props.

// ...
function Home(props) {
    return(
        <div>
            // ...
            <button onClick={() => {
                props.navigation.goBack();
            }}>BACK</button>
            <button
                onClick={() => {
                    props.navigation.navigate('/posts');
                }}>Posts</button>
            // ...
        </div>
    );
}
// ...

OR for a more declarative approach opt for the Anchor compoennt

<Anchor href="/posts">Posts</Anchor>

The navigation object also exposes information such as navigation.location. It's the same as window.location but it will always be up to date and correct regardless of if browser routing has been disabled.

Passing Parameters to Screens

To pass data to the next screen, pass a value to the navigate function.

props.navigation.navigate('/posts', {
    post: {
        title: "Post"
    }
});

// Or with Anchor component
<Anchor href="/posts" params={{
    post: {
        title: "Post"
    }
}}>Posts</Anchor> // For cross domain URLs the params are appended as search parameters.

To access this data on the next screen:

// Screen: POSTS
// ...
<h1>{props.route.params.post.title}</h1>
// ...

All data passed to the navigate function is accessible on the target screen through the route prop.

Parameters can also be parsed from URL parameters for example a pathname with a search part such as /slides?hero=0 will be parsed into an object with key hero and value 0. To customise this behaviour you can pass a custom deserialiser or serialiser function to the Router component which will be used to convert between URL parameters and React Motion Router parameters and vice-versa.

<Router
    config={{
        paramsSerialiser: (params) => {
            const searchPart = new URLSearchParams(params).toString()

            return btoa(searchPart); // search encoded as Base64 string
        },
        paramsDeserialiser: (b64SearchPart) => {
            const searchPart = atob(b64SearchPart.slice(1)); // start after the ?
            const searchParams = new URLSearchParams(searchPart);

            const params = {};
            for (let [key, value] of searchParams) {
                params[key] = value;
            }

            return params;
        }
    }}
>
// ...
</Router>

In this example /slides?hero=0 becomes /slides?aGVybz0w.

Default Parameters

A default parameter can be passed to the screen by passing a value to the defaultParams prop on Stack.Screen component.

// ...
<Stack.Screen path="/posts" component={Posts} defaultParams={{
    post: {
        title: "Default Title"
    }
}}/>
// ...

Transitions

Transitions are a feature baked into react-motion-router; hence the name... To transition between screens do:

<Router config={{
    animation: {
        type: "slide",
        direction: "right",
        duration: 300
    }
}}>
// ...
</Router>

You can provide custom keyframes and options to customise and extend the types of animations available.

<Router config={{
    animation: {
        in: {
            keyframes: [{opacity: 0}, {opacity: 1}],
            options: {
                duration: 350,
                easing: 'ease'
            }
        },
        out: {
            keyframes: [{opacity: 1}, {opacity: 0}],
            options: {
                duration: 350,
                easing: 'ease-out'
            }
        }
    }
}}>
// ...
</Router>

You can subscribe to the transition progress by using the motion consumer component.

import {Motion} from 'react-motion-router';

// ...
<Motion.Consumer>
    {(progress) => {
        return (
            <div>{progress}</div>
        );
    }}
</Motion.Consumer>

// OR Class.contextType

static contextType = Motion;

The progress is updated as the animation plays and can be used to interpolate DOM style attributes or control playback of an animation.

Shared Element Transition

To do a shared element transition wrap the component you would like shared between screens and supply it with a unique ID prop.

// Screen: HOME
// ...
<SharedElement id="post">
    <h1>Post</h1>
</SharedElement>
// ...

and on another screen:

Screen: POSTS
// ...
<SharedElement id="post">
    <h1>Post</h1>
</SharedElement>
// ...

That's it! The element will transition from one screen to the next seemlessly. They can even do layered animations.

<SharedELement id="post" config={{
    x: {
        duration: 100
    },
    y: {
        duration: 300
    }
}}>
    <h1>Post</h1>
</SharedElement>

This way the X and Y axis are animated independently and can alter the path of the shared element while transitioning. Note that these durations are clamped to the overall router transition duration.

API Documentation

Stack.Screen

Stack.Screen Config

Router Config

AnimationConfig

SharedElement

SharedElement Config

It is useful to note that the duration and easing function properties can also be set on the X and Y axis as independent values by specifying an X or Y property on the shared element config object.

// ...
config={{
    x: {
        easingFunction: "ease-in-out",
        duration: 500
    }
}}
// ...

Remarks

This is a work in progress and elements of this solution are subject to change. There are a few limitations to be aware of for example there is:

• no analogue for HashRouter in this solution.
• no nested routing although there are plans to add this eventually.

Credits

Shoutout to @IzjerenHein whose react-native-shared-element was a source of great inspiration for this project 🙏.

Other Relevant Resources

1. material.io
2. react-native-magic-move
3. Hein Rutjes React Europe Talk
4. Shared Element Transitions for Web