Using CSS same-document view-transitions with React

Installation

``sh
npm install use-view-transitions
`

Overview

CSS view transitions are a new feature that allows for expressive
animations between states.

The main syntax for view-transitions looks something like this:

`js
document.startViewTransition(() => updateDOMAndReturnPromise())
`

There are several ways to use this API in a React or NextJS single-page app.

React

$3

This is the most basic way, and it doesn't require too much magic.

`js
document.startViewTransition(() =>
ReactDOM.flushSync(() => {
// set the "after" state here, synchronously.
}),
)
`

This approach should work for the common cases, but some apps don't work well
with synchronous updates. For example, some components might rely on some fast
asynchronous work to display correctly. When using flushSync,
any asynchronous work would be rendered after the transition is complete.

$3

This hook would work for asynchronous operations, and would work without flushSync out of the box.
By default, it works like React.startTransition,
but would execute the CSS view-transition without a flushSync:

`jsx
import { useViewTransition } from 'use-view-transitions/react'

const { startViewTransition } = useViewTransition()
const [value, increment] = useReducer((x) => x + 1, 0)
return (
<>
startViewTransition(() => increment())}>
Increment

{value}

)
`

Using useViewTrantision together with the component, you can suspend
capturing the new state until ready.

`jsx
import {
useViewTransition,
SuspendViewTransition,
} from 'use-view-transitions/react'
const { startViewTransition } = useViewTransition()
const [isLoading, setLoading] = useState(false)

// Don't use this code for real, it's simulation for something that loads asynchronously.
useEffect(() => {
if (isLoading) {
setTimeout(() => {
setLoading(false)
}, 100)
}
}, [isLoading])

return (
<>
onClick={() =>
startViewTransition(() => {
setLoading(true)
})
}
>
Load

{
// This would suspend capturing the "new" state of the transition until loaded.
isLoading ? : null
}

)
`

Note that like in the flushSync case, unrelated changes wrapped in React.startTransition would only
execute as part of capturing the new state.

NextJS

Since NextJS is based on React, using the above technique would work in most cases.
However, some state changes and event handlers happen within NextJS itself, e.g. navigating
to routes based on link clicks.

$3

For that, we offer the useNextRouterViewTransitions() hook:

`jsx
// _app.js

import { useNextRouterViewTransitions } from 'use-view-transitions/next'

useNextRouterViewTransitions()

return (



)
`

The hook listens to NextJS's router events
and uses the React hook internally to make sure that the old state is captured before the navigation is executed.

$3

With AppRouter, we don't have router events, so there's no good signal of when a navigation starts.
We can still use usePathname and useSearchParams to understand when a navigation is completed, but we have to do something
to make sure the old state is capture before we start the navigation.

For that, we could either implement our own element, wrap the existing one, or capture clicks - which is what
AutoViewTransitionsOnClick does. (Any of these ways is legit and has trade-offs).

Example:
`jsx
"use client";
import {AutoViewTransitionsOnClick, EnableNextAppRouterViewTransitions} from "use-view-transitions/next";

export default function RootLayout({
children,
}) {

return (

// This would make sure transition's new state is captured at the end of the route change.


// This captures link clicks and injects a view transition.


{children}


)
}
``

Examples

- A very simply NextJS example
- NextJS Movies App with view transitions (see live demo)
- Another simple example