react-transpose
react-transpose is a set of tools which helps you animate route or component transitions. It also enables you to animate shared-element transitions.
This package makes use of the awesome library popmotion for it's animations. This means that under the hood it uses the same spring / tween / etc.. animations types, and since this is a react package, it has some strong simularities with react-pose. In a way, this package can be seen as an extension on top of react-pose.
Why not use PoseGroup?
While PoseGroup is excellent in most use-cases probably way more suffisticated, sometimes it's hard to handle route specific configuration. What if you wanted to animate the entering direction of a component based on the route it was comming from? That's where react-transpose comes in: for each transition-state (enter / exit) it gives you additional props for acting on specific route-transitions. On top of that this package provides tools to create so called shared-element transitions.
Install
npm install --save react-transpose
or
yarn add react-transpose
This package has a peer-dependency on popmotion, so make sure to install this package together with popmotion@^8.6.0. If your project is using popmotion's react-pose there is no need to install popmotion since react-pose already has a dependency on it.
Usage
Simple demo
import * as React from "react";import SwitchGroup Stage transposedShared from "react-transpose"; const Box = transposedShared; { const currentStage setStage = React; // toggle stage every second React; return <div => <SwitchGroup => <Stage ="route-a" = /> <Stage ="route-b" = /> </SwitchGroup> </div> ;}
Other demo's
API
SwitchGroup
It's main purpose is to render the right <Stage />
out of one or multiple stages (paths/routes) given a current stage. It has a similar function to Switch in react-router.
Prop | type | required | Description |
---|---|---|---|
children | ReactNode[] | yes | Must be one or more <Stage /> elements |
stage | string | yes | the current stage |
setStage | (stage: string) => void | no | Use in combination with useStage to set a stage from deeper within the tree |
example
import SwitchGroup Stage from "react-transpose"; { const currentStage setStage = React; return <SwitchGroup = => <Stage ="a" = /> <Stage ="b" = /> </SwitchGroup> ;}
Stage
Used to represent a stage or path, much like a <Route />
in react-router.
Use either the render or the component prop.
Prop | type | required | Description |
---|---|---|---|
stage | string | yes | |
render | () => ReactElement | no | |
component | Component | no |
useStage
Helper hook to set a stage from deeper within the tree. Note: the 'setStage' prop must be given to the <SwitchGroup />
component.
import useStage from "react-transpose"; { const setStage = ; return <button =>Goto next route</button>;}
Group
Similar to <SwitchGroup />
, but lets you handle the routing mechanism. Useful in combination with react-router for example.
Prop | type | required | Description |
---|---|---|---|
currentPath | string | yes | path of current location |
children | ReactElement | yes | Can only be one child at a time |
example with react-router
{ return <Group => <Switch => <Route = = /> <Route = = /> </Switch> </Group> ;}
transposed
Function which creates components with animation capabilities. As with libraries as styled-components and react-pose, you can either pass in a existing component (don't forgot to forward the ref to a dom-node), or a tag name. So these all work:
// existing componentimport Box from "./Box";const AnimatedBox = ; // argument stringconst AnimatedBox = ; // helper methodconst AnimatedBox = transposed;
Config
Prop | type | required | Description |
---|---|---|---|
animateFirst | boolean | no | defaults to false. Determines whether to animate entering the first route |
enter | object | (props: TransitionProps) => object |
yes | see below |
exit | object | (props: TransitionProps) => object |
yes | see below |
The enter
and exit
prop takes either a function returning an object, or a plain object. It is almost the same as how react-pose does it. For example:
const Box = transposed
When passing a function, you'll get a object with these properties
Prop | Type | Description |
---|---|---|
path | { from: string: to: string } |
|
props | object | Provides access to the wrapped component's props |
direction | "in" | "out" |
Especially useful for exit . When entering, react-transpose looks at the exit state to determine where to animate from. In that case the direction is "in". When exiting, react-transpose looks at the exit state again, only this time with direction "out" |
For example:
const Box = transposed;
transposedShared
Quite similar to transposed, but it's main purpose is to animate shared-element transitions.
Config
Prop | type | required | Description |
---|---|---|---|
sharedKey | string | (props: object) => string |
yes | for identifying shared elements |
animationProps | string[] | yes | style-props to be animated |
transition | object | (props: TransitionProps) => object |
yes | see below |
whenNotShared | { enter: object; exit: object; animatedFirst: boolean } |
no | see below |
Example:
const Box = transposedShared; const BoxContext = React; { const gotoDetail = React; return <div> <Box ="1" = /> <Box ="2" = /> <Box ="3" = /> <Box ="4" = /> </div> ;} { const gotoList selectedBox = React; return <> <button =>Back</button> <Box = /> </> ;} { const state setState = React; const payload = React; return <BoxContext.Provider => <SwitchGroup => <Stage ="list" = /> <Stage ="detail" = /> </SwitchGroup> </BoxContext.Provider> ;}
License
MIT © everweij