T
r
a
n
s
i
t
i
o
n
L
i
n
k

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.

  1. Call a trigger function to manipulate the DOM with something like gsap.
  2. 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:

  1. transitionStatus
  2. entry
  3. 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>