@joycostudio/transitions

  JOYCO Transitions

Plug & Play page transitions for React Router. See it in action in our demo page.

pnpm add @joycostudio/transitions

📖 Documentation

Core Components

RouteTransitionManager

The main component responsible for managing route transitions. It wraps your route content and handles all transition states. It NEEDS to have anchor a ref to some element so it can be preserved on unmount. If you don't want to mess the inner children layout with a wrapper just do <div style={{ display: 'contents' }} ref={ref}>{myUltraDelicateChildren}</div>.

<RouteTransitionManager
  routes={routes}
  pathname={location.pathname}
  mode="out-in"
  onEnter={{
    default: async (node) => {
      // Your enter animation
    },
  }}
  onExit={{
    default: async (node) => {
      // Your exit animation
    },
  }}
>
  {(nodeRef) => <div ref={nodeRef}>{/* Your route content */}</div>}
</RouteTransitionManager>

Props:

• children: Function that receives a ref to be attached to your route content
• pathname: Current route pathname
• mode: Transition mode ('out-in' | 'in-out')
• onEnter: Record of enter animations by route or default
• onExit: Record of exit animations by route or default
• onEntering: Optional callbacks when entering starts
• onEntered: Optional callbacks when entering completes
• onExiting: Optional callbacks when exiting starts
• onExited: Optional callbacks when exiting completes
• appear: Whether to animate on first render
• routes: Array of route configurations

DocumentTransitionState

A utility component that adds a data-transition-state attribute to the document root, useful for controlling UI elements during transitions.

<DocumentTransitionState />

✨ TIP | Lock links while transitioning

If you use the <DocumentTransitionState /> component. It will attach a data-transition-state to the document's root. You can use it to disable all the links while the page is transitioning to make the experience feel more controlled.

/* Disable links during transitions */
html:not([data-transition-state='idle']) a {
  pointer-events: none;
}

Hooks

usePreservedLoaderData<T>()

Returns a frozen version of the loader data to prevent data changes during transitions.

const data = usePreservedLoaderData<YourDataType>()

useTransitionState()

Returns the current transition state and helper flags.

const {
  state, // 'entering' | 'exiting' | 'idle'
  isEntering, // boolean
  isExiting, // boolean
  isIdle, // boolean
} = useTransitionState()

🤖 Automatic Workflows

This template comes with two GitHub Actions workflows (currently disabled for convenience):

• Release Workflow (.github/workflows/release.yml): Automates the release process using Changesets. When enabled, it will automatically create release pull requests and publish to npm when changes are pushed to the main branch.

• Publish Any Commit (.github/workflows/publish-any-commit.yml): A utility workflow that can build and publish packages for any commit or pull request.

🦋 Version Management

This library uses Changesets to manage versions and publish releases. Here's how to use it:

Adding a changeset

When you make changes that need to be released:

pnpm changeset

This will prompt you to:

• Select which packages you want to include in the changeset
• Choose whether it's a major/minor/patch bump
• Provide a summary of the changes

Creating a release

To create a new version and update the changelog:

# 1. Create new versions of packages
pnpm version:package

# 2. Release (builds and publishes to npm)
pnpm release

Remember to commit all changes after creating a release.