Adding Page Transitions with gatsby-plugin-transition-link
This guide will cover how to use
gatsby-plugin-transition-link to animate transitions between pages on your Gatsby site.
TransitionLink component provides a way of describing a page transition via props on a Link component. It works with many animation libraries, like react-pose, GSAP, animejs, and many others.
Note that currently, as the plugin is based on link navigation, transitions when navigating with the browser buttons are not supported.
For other page transition options, see the overview on adding page animations.
First, install the plugin:
Make sure to add the plugin to your
Finally, import the
TransitionLink component wherever you want to use it:
You can use the
AniLink component to add page transitions without having to define your own custom transitions. It’s a wrapper around
TransitionLink that provides 4 predefined transitions:
paintDrip. You can preview them at this demo site.
To use AniLink, you will need to install the
gsap animation library:
Then, import the AniLink component:
Finally, make sure you provide your desired animation’s name as a blank prop to
Options like transition duration, direction, and more are customizable with props. See the documentation of AniLink for more details.
You have two main methods of creating page transitions:
- Use the
triggerfunction defined in your
entryprop. More details in the ’Using the
- Use the props passed by
TransitionLinkto define your transitions. More details in the ’Using passed props’ subsection.
Additionally, you can specify a number of props and options on the
TransitionLink component, like
delay, and more. For more options and details, see the documentation of TransitionLink. For further examples of usage, visit the plugin’s GitHub repository.
Using the trigger function
You can specify a
trigger function that will handle the animation. This is useful for imperative animation libraries like animejs or GSAP that specify animations with function calls.
Using passed props
The exiting and entering pages/templates involved in the transition will receive props indicating the current transition status, as well as the
entry props defined on the
You can combine these props with a declarative state-based animation libraries like react-pose or react-spring to specify transitions for exiting and entering a page.
If you want to access these props in one of your components instead of a page/template, you should wrap your component in the
TransitionState component. This component takes a function that will have access to the same props as above, which you can then use in your component.
Here’s an example using
react-pose to trigger enter/exit transitions for a
Box component will be aware of whether the page it’s a child of is mounting or unmounting, and it will fade in/out accordingly.
Excluding elements from page transitions
You may want to have elements on a page that persist throughout the page transition (ex. a site-wide header). This can be accomplished by wrapping elements in a persistent layout component by using the following plugin option in your
As always, check out the installation docs for more information.