react-transition-context

Helps you deal with nested transitions

npm install --save-dev react-transition-context

Table of Contents

• Introduction
• TransitionState enum
• Overall transition state
  • Table
• API
  • TransitionContext component
  • useTransitionContext hook
  • useTransitionStateEffect hook
  • useAppearingEffect hook
  • useAppearedEffect hook
  • useEnteringEffect hook
  • useEnteredEffect hook
  • useCameInEffect hook
  • useLeavingEffect hook
  • useLeftEffect hook
  • useAutofocusRef hook

Introduction

These days it's fairly easy to animate transitions between your app routes using React components. But it adds difficulty to other things, like focusing an input when a form appears. If the form is part of the initial page load, the input should be focused immediately after mounting. But if you transition to the form from some other route, the input shouldn't be focused until the transition ends. So you need to know if a transition is in progress and take action when it ends.

To make matters worse, there may be nested transitions. For example, in my app, I have a fade transition between the /users and /organizations routes, but within the /users route, I have a drilldown transition from /users to /users/:userId. If the user is in /organizations/yolo and clicks a link to /users/jimbo, there will be a fade transition, but not a drilldown transition. So the /users/:userId form needs to know if either the fade or drilldown transition is going before it focuses an input.

react-transition-context solves this problem. If the fade and the drilldown both put use it to put their transition state on React context, the /users/:userId form can register a effect to get called when it's fully in (rather than mounted but appearing or entering).

TransitionState enum

There are five possible values:

• 'appearing'
• 'entering'
• 'in'
• 'leaving'
• 'out'

Overall transition state

The overall transition state takes into account both a transition component's own transition state, and the overall transition state of its closest ancestor transition component.

For example:

• If the ancestor is 'in' and the descendant is 'entering', the overall transition state is 'entering'.
• If the ancestor is 'leaving' and the descendant is 'entering', the overall transition state is 'leaving'.
• If the ancestor is 'out' and the descendant is 'leaving', the overall transition state is 'out'.

Table

| ↓ Ancestor / Descendant → | 'appearing' | 'entering' | 'in' | 'leaving' | 'out' | | :------------------------ | :------------ | :------------ | :------------ | :---------- | ------- | | 'appearing' | 'appearing' | 'appearing' | 'appearing' | 'leaving' | 'out' | | 'entering' | 'appearing' | 'entering' | 'entering' | 'leaving' | 'out' | | 'in' | 'appearing' | 'entering' | 'in' | 'leaving' | 'out' | | 'leaving' | 'leaving' | 'leaving' | 'leaving' | 'leaving' | 'out' | | 'out' | 'out' | 'out' | 'out' | 'out' | 'out' |

API

TransitionContext component

import { TransitionContext } from 'react-transition-context'

Props

state: TransitionState (optional)

The transition state of your transition component that is rendering this. Omit this if you just want to consume the overall transition state without changing the value for descendants.

children: React.Node (required)

The content to render

useTransitionContext hook

import { useTransitionContext } from 'react-transition-context'

Hook that returns the overall transition state from context.

useTransitionStateEffect hook

import { useTransitionStateEffect } from 'react-transition-context'

useTransitionStateEffect(
  effect: (prevState: ?TransitionState, nextState: TransitionState) => any
)

Calls effect whenever the overall transition state from context changes. prevState will be null for the first call (on mount).

useAppearingEffect hook

import { useAppearingEffect } from 'react-transition-context'

useAppearingEffect(
  effect: (prevState: ?TransitionState, nextState: TransitionState) => any
)

Calls effect whenever the overall transition state from context changes from 'out'/'leaving' to 'appearing', or is 'appearing' when the component mounts.

useAppearedEffect hook

import { useAppearedEffect } from 'react-transition-context'

useAppearedEffect(
  effect: (prevState: ?TransitionState, nextState: TransitionState) => any
)

Calls effect whenever the overall transition state from context changes from 'appearing' to 'in'.

useEnteringEffect hook

import { useEnteringEffect } from 'react-transition-context'

useEnteringEffect(
  effect: (prevState: ?TransitionState, nextState: TransitionState) => any
)

Calls effect whenever the overall transition state from context changes from 'out'/'leaving' to 'entering', or is 'entering' when the component mounts.

useEnteredEffect hook

import { useEnteredEffect } from 'react-transition-context'

useEnteredEffect(
  effect: (prevState: ?TransitionState, nextState: TransitionState) => any
)

Calls effect whenever the overall transition state from context changes from 'entering' to 'in'.

useCameInEffect hook

import { useCameInEffect } from 'react-transition-context'

useCameInEffect(
  effect: (prevState: ?TransitionState, nextState: TransitionState) => any
)

Calls effect whenever the overall transition state from context changes to 'in' (from any other state), or is 'in' when the component mounts.

useAutofocusRef is built on top of this.

useLeavingEffect hook

import { useLeavingEffect } from 'react-transition-context'

useLeavingEffect(
  effect: (prevState: ?TransitionState, nextState: TransitionState) => any
)

Calls effect whenever the overall transition state from context changes from 'in'/'appearing'/'entering' to 'leaving', or when the component will unmount and the overall transition state is 'in'/'appearing'/'entering'.

useLeftEffect hook

import { useLeftEffect } from 'react-transition-context'

useLeftEffect(
  effect: (prevState: ?TransitionState, nextState: TransitionState) => any
)

Calls effect whenever the overall transition state from context changes from 'leaving' to 'out'.

useAutofocusRef hook

Creates a ref you can pass to an element to automatically focus it when the component comes in

Example

import * as React from 'react'
import { useAutofocusRef } from 'react-transition-context'

const LoginForm = () => {
  const autofocusRef = useAutofocusRef()
  return (
    <form>
      <input type="text" name="username" ref={autofocusRef} />
      <input type="password" name="password" />
    </form>
  )
}

useTransitionStateEffectFilter

import { useTransitionStateEffectFilter } from 'react-transition-context'

useTransitionStateEffectFilter: (
  filter: (prevState: ?TransitionState, nextState: TransitionState) => boolean
) => (
  effect: (prevState: ?TransitionState, nextState: TransitionState)
) => void

A higher-order function that takes a filter function and returns a transition state hook that only calls effect when the filter returns truthy.

(useTransitionStateEffectFilter is used to create all the useAppearingEffect, useLeavingEffect, etc hooks)