---
title: instant
description: API reference for the instant route segment config.
url: "https://nextjs.org/docs/app/api-reference/file-conventions/route-segment-config/instant"
docs_index: /docs/llms.txt
prerequisites:
  - "File-system conventions: /docs/app/api-reference/file-conventions"
  - "Route Segment Config: /docs/app/api-reference/file-conventions/route-segment-config"
related:
  - app/guides/instant-navigation
  - app/getting-started/caching
  - app/getting-started/revalidating
  - app/api-reference/directives/use-cache
---


> For an index of all Next.js documentation, see [/docs/llms.txt](/docs/llms.txt).
The `unstable_instant` route segment config opts a route into validation for instant client-side navigations. Next.js checks, during development and at build time, that the caching structure produces an instant [static shell](/docs/app/glossary#static-shell) at every possible entry point into the route.

> **Good to know**:
>
> * The `unstable_instant` export only works when [`cacheComponents`](/docs/app/api-reference/config/next-config-js/cacheComponents) is enabled.
> * `unstable_instant` cannot be used in Client Components. It will throw an error.

```tsx filename="layout.tsx | page.tsx" switcher
export const unstable_instant = {
  prefetch: 'static',
}

export default function Page() {
  return <div>...</div>
}
```

```jsx filename="layout.js | page.js" switcher
export const unstable_instant = {
  prefetch: 'static',
}

export default function Page() {
  return <div>...</div>
}
```

## Reference

### `prefetch`

Controls the validation and prefetching mode.

```tsx filename="page.tsx"
export const unstable_instant = {
  prefetch: 'static',
}
```

* **`'static'`**: Enables validation. Prefetching behavior stays the same (static by default). Components that read cookies or headers are treated as dynamic and must be behind Suspense.

### Disabling instant

Set `false` to exempt a segment from validation:

```tsx filename="app/dashboard/layout.tsx"
export const unstable_instant = false
```

## How validation works

`unstable_instant` triggers validation at every shared layout boundary in the route. Validation runs during development (on page loads and HMR updates) and at build time. Errors appear in the dev error overlay or fail the build.

Each error identifies the component that would block navigation. The fix is usually to cache the data with `use cache` or wrap it in a `<Suspense>` boundary.

## Inspecting loading states

Enable the DevTools toggle with the experimental flag:

```js filename="next.config.js"
module.exports = {
  experimental: {
    instantNavigationDevToolsToggle: true,
  },
}
```

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 that was 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.

Use both to check that your loading states look right on first visit and on navigation.

## Testing instant navigation

The `@next/playwright` package exports an `instant()` helper that holds back dynamic content while the callback runs against the static shell. See the [guide](/docs/app/guides/instant-navigation#prevent-regressions-with-e2e-tests) for a full example.

```typescript
import { instant } from '@next/playwright'
```

## Known issue: shared cookie across projects

The DevTools use a `next-instant-navigation-testing` cookie to freeze the UI at the static shell. Because cookies are scoped to the domain and not the port, running multiple projects on the same domain (typically `localhost`) means the cookie is shared across them and can cause unexpected behavior. Clear the cookie or close the Instant Navs panel when switching between projects to avoid issues.

> **Good to know:** This will be fixed as part of stabilizing the feature.

## TypeScript

```tsx
type RuntimeSample = {
  cookies?: Array<{ name: string; value: string }>
  headers?: Array<[string, string]>
  params?: Record<string, string | string[]>
  searchParams?: Record<string, string | string[]>
}

type InstantConfig =
  | false
  | {
      prefetch: 'static'
      from?: string[]
      unstable_disableValidation?: boolean
    }
  | {
      prefetch: 'runtime'
      samples: RuntimeSample[]
      from?: string[]
      unstable_disableValidation?: boolean
    }

export const unstable_instant: InstantConfig = {
  prefetch: 'static',
}
```

## Version History

| Version   | Changes                                                      |
| --------- | ------------------------------------------------------------ |
| `v16.x.x` | `unstable_instant` export introduced (Cache Components only) |
## Next Steps

Learn how to use instant navigations in practice.

- [Caching](/docs/app/getting-started/caching)
  - Learn how to cache data and UI in Next.js
- [Revalidating](/docs/app/getting-started/revalidating)
  - Learn how to revalidate cached data using time-based and on-demand strategies.
- [use cache](/docs/app/api-reference/directives/use-cache)
  - Learn how to use the "use cache" directive to cache data in your Next.js application.

---

For a semantic overview of all documentation, see [/docs/sitemap.md](/docs/sitemap.md)

For an index of all available documentation, see [/docs/llms.txt](/docs/llms.txt)