Documentation
Overview
Learn how Segue runs a Route Transition before you add it to your application.What Segue is
Segue coordinates Route Transitions in Next.js App Router applications. A Route Transition is the visual handoff from one route to another.
The current API runs a Cover before navigation. A Cover places temporary visuals above the current route. When it finishes, Segue asks Next.js to navigate and keeps the final Cover state mounted until that navigation settles.
You provide the React markup, CSS, and animation. Segue handles when that UI appears, when navigation starts, and when the UI is removed. If the animation fails or exceeds its timeout, navigation can still continue.
Segue is not an animation library and doesn't provide ready-made effects. You can use the Web Animations API, Motion, GSAP, CSS, or another animation system.
The pieces Segue connects
Assign your visual effect to destination routes, then connect it to navigation:
| Piece | What you provide |
|---|---|
| Route-Transition Preset | The temporary UI and Cover animation for a reusable effect. |
| Manifest | A list that assigns a Preset to each exact destination path. It can also include image data for that destination. |
| Provider | A shared component that gives Segue the Presets and manifest. |
| Link | A Next.js link whose navigation Segue should coordinate. |
In the standard path, a Link points to a destination, the manifest selects its Preset, and the Provider displays that Preset's Cover from a shared layout. This keeps the visual mounted while Next.js replaces the route tree.
A Link can also provide a Route-Transition Override for one navigation. An Override runs source-specific Cover code instead of the destination's Preset. A Transition Image is an optional image prepared for a Preset or Override.
The manifest contains plain data and can be imported by Server Components. Presets and the Provider render or animate HTML elements, so they belong in Client Components.
How a transition works
After Segue accepts a navigation, it follows these steps:
| Step | What happens |
|---|---|
| Selection | Segue tries the link's Override, if it has one. If the Override declines or fails, Segue uses the Preset assigned to the destination path. |
| Cover | The selected visual work runs while the current route remains on screen. Navigations with no visual work skip this step. |
| Navigation | When the Cover finishes, fails, or times out, Segue calls the Next.js router. |
| Settlement | Next.js finishes the navigation. Segue clears its pending state and removes any Preset UI. |
A Destination Entrance animates content inside the new route after it appears. Segue coordinates the Cover. Your destination components control the Destination Entrance.
Image Warming is optional and happens before this sequence. Segue can start loading Transition Images when a link comes within 300 pixels of the viewport or receives mouse, keyboard-focus, or touch input. Segue never waits for Image Warming before navigation.
When Segue is a good fit
Use Segue when your application meets all of these conditions:
- It uses Next.js
>=16.3.1 <17, React>=19.2 <20, and the App Router. - Its Route Transitions need project-specific visuals rather than built-in effects.
- You can assign a standard Route-Transition Preset to each destination path.
- You want navigation to continue if animation work fails or times out.
Segue is probably not the right fit if you use the Pages Router, need transitions for another React router, or want a ready-made animation component. Read Scope and limitations to learn which tasks Segue does and does not handle.
If these requirements match your application, continue to Installation, then build your first transition.