Ensuring instant navigations

With Cache Components enabled, use cache and <Suspense> let you control what gets cached and what streams in dynamically. When these are in the right place, client-side navigations are instant.

The unstable_instant route segment config helps you place <Suspense> boundaries and use cache correctly. Add it to any page or layout and Next.js will check during development that navigating to that route produces an instant static shell.

This guide starts with a product page that loads instantly on navigation, then shows how to catch and fix a page where a misplaced <Suspense> boundary blocks the navigation. Nothing visible changes until the server finishes rendering.

A page that navigates instantly

A product page at /store/[slug] that fetches two pieces of data: product details (name, price) and live inventory.

• There is no generateStaticParams, meaning slug is only known at request time
• Both components await params to get the slug, which suspends. Each has its own <Suspense> boundary
• Product info rarely changes and is queried from the db using a cached function
• Inventory must be fresh on each request. The db query is inside a <Suspense> boundary

import { Suspense } from 'react'
import { db } from '@/lib/db'
 
export const unstable_instant = true
 
export default function ProductPage(props: PageProps<'/store/[slug]'>) {
  return (
    <div>
      <Suspense fallback={<p>Loading product...</p>}>
        <ProductInfo params={props.params} />
      </Suspense>
      <Suspense fallback={<p>Checking availability...</p>}>
        <Inventory params={props.params} />
      </Suspense>
    </div>
  )
}
 
type Params = PageProps<'/store/[slug]'>['params']
 
async function ProductInfo({ params }: { params: Params }) {
  const { slug } = await params
  const product = await getProduct(slug)
  return (
    <>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
    </>
  )
}
 
async function getProduct(slug: string) {
  'use cache'
  return db.products.findBySlug(slug)
}
 
async function Inventory({ params }: { params: Params }) {
  const { slug } = await params
  const item = await db.inventory.findBySlug(slug)
  return <p>{item.count} in stock</p>
}

The unstable_instant export tells Next.js to check that navigating to this page from any other page in your app is instant. It does this during development. If a component would delay the transition (for example, by fetching uncached data without a local <Suspense> boundary), the error overlay tells you which one and suggests a fix.

Validation runs automatically on every page load using the real request from your browser, so dynamic params like [slug] are checked against actual values as you navigate.

Visualize loading states with the Next.js DevTools

The Next.js DevTools let you see what users see on page loads and client navigations before dynamic data streams in. Use it to verify your loading states look right, check that the right content appears immediately, and iterate on where to place <Suspense> boundaries.

Enable the toggle in your Next.js config:

import type { NextConfig } from 'next'
 
const nextConfig: NextConfig = {
  cacheComponents: true,
  experimental: {
    instantNavigationDevToolsToggle: true,
  },
}
 
export default nextConfig

Open the Next.js DevTools and select Instant Navs. Two options are available:

• Page load: click Reload to refresh the page and freeze it at the initial static UI generated for this route, before any dynamic data streams in.
• Client navigation: once enabled, clicking any link in your app shows the prefetched UI for that page instead of the full result.

Try a page load on the product page. Two separate fallbacks appear: "Loading product..." and "Checking availability...". On the first visit the cache is cold and both fallbacks are visible. Navigate to the page again and the product name appears immediately from cache.

Now try a client navigation (click a link from /store/shoes to /store/hats). The product name and price appear immediately (cached). "Checking availability..." shows where inventory will stream in.

Prevent regressions with e2e tests

Validation catches structural problems during development. To prevent regressions as the codebase evolves, the @next/playwright package includes an instant() helper that asserts on exactly what appears in the instant shell:

import { test, expect } from '@playwright/test'
import { instant } from '@next/playwright'
 
test('product title appears instantly', async ({ page }) => {
  await page.goto('/store/shoes')
 
  await instant(page, async () => {
    await page.click('a[href="/store/hats"]')
    await expect(page.locator('h1')).toContainText('Baseball Cap')
  })
 
  // After instant() exits, dynamic content streams in
  await expect(page.locator('text=in stock')).toBeVisible()
})

Inside the instant() callback, only the static shell is visible. After the callback finishes, dynamic content streams in and you can assert on the full page.

There is no need to write an instant() test for every navigation. Use instant() for the user flows that matter most. In the future build-time instant validaiton will be available to cover a broader set of navigation cases.

Fixing a navigation that blocks

Now consider a different route, /shop/[slug]. For the sake of this example it has the same data requirements as /store/[slug], but is implemented without local <Suspense> boundaries or caching:

import { db } from '@/lib/db'
 
export default async function ProductPage(props: PageProps<'/shop/[slug]'>) {
  const { slug } = await props.params
  const product = await db.products.findBySlug(slug)
  const item = await db.inventory.findBySlug(slug)
  return (
    <div>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
      <p>{item.count} in stock</p>
    </div>
  )
}

The root layout wraps {children} in a <Suspense> boundary:

export default function RootLayout({
  children,
}: {
  children: React.ReactNode
}) {
  return (
    <html lang="en">
      <body>
        <Suspense fallback={<p>Loading...</p>}>{children}</Suspense>
      </body>
    </html>
  )
}

On an initial page load, the root <Suspense> catches the async work and streams the page in behind the fallback.

Everything appears to work. But on a client navigation from /shop/shoes to /shop/hats, the shared layout is /shop and only the content below it re-renders. The root <Suspense> boundary is above that layout and is not triggered for this navigation. The page fetches uncached data with no local boundary, blocking the navigation until the server finishes rendering.

You can see this with the DevTools. Try a page load: the root <Suspense> catches everything and "Loading..." appears. Now try a client navigation between two /shop/ pages: no prefetched UI shows up because there is no <Suspense> boundary below the shared layout. Navigations from other routes to /shop/ appear blocked too.

Step 1: Add instant validation

Add an unstable_instant export to the page to surface the problem:

import { db } from '@/lib/db'
 
export const unstable_instant = true
 
export default async function ProductPage(props: PageProps<'/shop/[slug]'>) {
  const { slug } = await props.params
  const product = await db.products.findBySlug(slug)
  const item = await db.inventory.findBySlug(slug)
  return (
    <div>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
      <p>{item.count} in stock</p>
    </div>
  )
}

Next.js now simulates navigations at every shared layout boundary in the route. In this case, both components await params and access uncached data. These need to be wrapped by a <Suspense> boundary. The first thing validation catches is the await params at the top level.

Step 2: Fix the validation error

There is no generateStaticParams here, slug is only known at request time. Because awaiting params suspends, the page component can't do it at the top level. Instead, move the await params into separate components, pass params to each, and wrap them with <Suspense>.

For each component, decide:

Product details (name, price) rarely change. Cache the data function with use cache:

async function ProductInfo({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const product = await getProduct(slug)
  return (
    <>
      <h1>{product.name}</h1>
      <p>${product.price}</p>
    </>
  )
}
 
async function getProduct(slug: string) {
  'use cache'
  return db.products.findBySlug(slug)
}

Inventory must be fresh each request. Leave it uncached:

async function Inventory({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params
  const item = await db.inventory.findBySlug(slug)
  return <p>{item.count} in stock</p>
}

The page passes params to each component and wraps them with <Suspense>:

import { Suspense } from 'react'
import { db } from '@/lib/db'
 
export const unstable_instant = true
 
export default function ProductPage(props: PageProps<'/shop/[slug]'>) {
  return (
    <div>
      <Suspense fallback={<p>Loading product...</p>}>
        <ProductInfo params={props.params} />
      </Suspense>
      <Suspense fallback={<p>Checking availability...</p>}>
        <Inventory params={props.params} />
      </Suspense>
    </div>
  )
}

Validation passes. Open the DevTools and try a client navigation. The product name and price appear immediately, and "Checking availability..." shows where inventory will stream in.

Opting out with instant = false

Not every layout or page can be instant. A dashboard layout that reads cookies and fetches user-specific data might be too dynamic for the first visit. You can set instant = false on any layout or page to exempt it from validation:

export const unstable_instant = false

This tells validation: navigating to /dashboard from outside does not need to be instant, but sibling navigations within it still do. Navigating from /dashboard/a to /dashboard/b can still be checked by adding instant to the page segments under /dashboard.

Next steps

• instant API reference for all configuration options, including runtime prefetching and incremental adoption with instant = false
• Caching for background on use cache, Suspense, and Partial Prerendering
• Revalidating for how to expire cached data with cacheLife and updateTag