TransitionLink
TransitionLink is a flexible and powerful way to write your own page transitions. If you want to use some default transitions with minimal effort, try AniLink.
Usage
There are two main ways to use TransitionLink.
- Call a trigger function to manipulate the DOM with something like gsap.
- Use the TransitionState component alongside TransitionLink or use page / template props to animate your components with something like react-spring, react-pose or CSS transitions.
Check below for documentation of all available props and transition options.
Here is a brief example of what a TransitionLink might look like for a function based gsap transition.
<TransitionLink
to="/page-2"
exit={{
trigger: ({ exit, node }) => this.interestingExitAnimation(exit, node),
length: 1
}}
entry={{
delay: 0.6
}}
>
Go to page 2
</TransitionLink>
This is an example of what a TransitionLink might look like for a state based transition using react-spring or react-pose. See the TransitionState component docs for more info on what your components might look like.
<TransitionLink
to="/page-2"
exit={{
length: 1
}}
entry={{
delay: 0.6
}}
>
Go to page 2
</TransitionLink>
Page / Template props
Your pages and templates will receive three props:
- transitionStatus
- entry
- exit
const PageOrTemplate = ({ children, transitionStatus, entry, exit}) => {
console.log(transitionStatus, entry, exit)
return <div className={transitionStatus}>{children}</div>;
}
transitionStatus contains the current page transitions status (either exiting, exited, entering, or entered).
exit and entry contain the entry and exit props and state passed from TransitionLink.
<TransitionLink
to="/page-2"
exit={{
length: 1
state: { pass: 'this to the exiting page' }
}}
entry={{
...
state: { you: 'can add anything you want here' }
}}
>
Go to page 2
</TransitionLink>
In some cases this can cause performance issues because there are extra re-renders happening on your pages or templates. You can disable this with a plugin option.
{
resolve: 'gatsby-plugin-transition-link',
options: {
injectPageProps: false,
},
},
Props and Options
to, activeClass & className props
These are used exactly as they are in gatsby-link.
<TransitionLink to="/page-2" activeClass="active" className="transition-link">
Go to page 2
</TransitionLink>
exit & entry props
Each takes an object of transition options to be applied to the exiting and entering pages respectively.
<TransitionLink
to="/page-2"
exit={{
... // exit transition options
}}
entry={{
... // entry transition options
}}
>
Go to page 2
</TransitionLink>
trigger option
This takes a function with access to the DOM node of the exiting or entering page, the users mouse event, and both the full exit and entry props.
exit={{
trigger: ({ node, e, exit, entry }) => console.log(node, e, exit, entry)
// here node refers to the DOM node of the exiting page
}}
entry={{
trigger: ({ node, e, exit, entry }) => console.log(node, e, exit, entry)
// here node refers to the DOM node of the entering page
}}
length option
This is the duration in seconds of the exit and/or entry animation. If no delay is specified these will start at the same time.
exit={{
length: 2
}}
entry={{
length: 1
}}
delay option
This is the duration in seconds to delay before beginning the animation. See the timeline for more information on how this effects animation duration.
entry={{
delay: 0.5
}}
zIndex option
This is the zIndex of the page wrapper.
exit={{
zIndex: 2 // exit default is 0
}}
entry={{
zIndex: 0 // entry default is 1
}}
state option
This is the state to be passed as props to the page or template component of the exiting or entering page. It is also accessible anywhere in your app using the TransitionState component.
exit={{
state: {
thisIs: 'passed to the exiting page'
}
}}
entry={{
state: {
thisIs: 'passed to the entering page'
}
}}
appearAfter option
The appearAfter option will keep a page hidden, but rendered for the amount of time specified. This is useful for if you want to measure an element on the page before displaying it.
<TransitionLink
entry={{
appearAfter: 2,
length: 1,
}}
>
Go to page 2
</TransitionLink>
trigger prop
The trigger prop takes a function that is the equivalent of combining the entry and exit trigger functions. This allows you to do things like measure elements on the entering and exiting pages and morph one element into another.
<TransitionLink
entry={{
appearAfter: 2,
length: 1,
}}
trigger={async pages => {
// wait until we have access to both pages
const exit = await pages.exit
const entry = await pages.entry
// here we can access both pages
// You could measure the entry element here
// start exit animation based on measurements if you want
// wait for the entering page to become visible
await entry.visible
// the entering page is visible here.
// if you want you can animate it now!
}}
>
Maybe morph to page 3
</TransitionLink>