nextjs-navigation

name	nextjs-navigation
description	Provides expert guidance on Next.js App Router navigation, prefetching behavior, Link component configuration, and client-side state preservation. Use when working with Next.js navigation, Link prefetching, Suspense boundaries during navigation, App Router routing, or PageProps typing.

Next.js Navigation

Expert guidance for Next.js App Router navigation patterns, prefetching behavior, and navigation-specific optimizations.

Link Prefetching Behavior

Prefetch behavior differs significantly between App Router and previous Next.js versions:

App Router Prefetch Props

• prefetch={false} - Disables all prefetching, including on hover. In previous Next.js versions, this would still prefetch on hover.
• prefetch={undefined} - Prefetches static routes only. Dynamic routes are not prefetched.
• prefetch={true} - Prefetches both static and dynamic routes.

Example:

// No prefetching at all
<Link href="/dashboard" prefetch={false}>Dashboard</Link>

// Prefetch static routes only (default behavior)
<Link href="/about" prefetch={undefined}>About</Link>

// Prefetch both static and dynamic routes
<Link href="/posts/[id]" prefetch={true}>Post</Link>

Choose prefetch={false} when navigation is unlikely or when the target page is resource-intensive. Use prefetch={true} for frequently accessed dynamic routes to improve perceived performance.

Suspense Boundaries and Search Params

Suspense boundaries do not re-trigger on same-page navigations when only search params change. This means loading states won't display when filtering or paginating via query parameters.

Force Suspense Re-trigger

Add a unique key prop to the Suspense boundary that includes the changing search param:

import { Suspense } from 'react';

export default function Page({ searchParams }: { searchParams: { filter?: string } }) {
  return (
    <Suspense key={searchParams.filter} fallback={<Loading />}>
      <DataTable filter={searchParams.filter} />
    </Suspense>
  );
}

The key change forces React to unmount and remount the Suspense boundary, displaying the fallback during data fetching. Use this pattern for filters, pagination, or any search param that triggers data fetching.

Type Safety

PageProps Helper Type

Use the PageProps helper type to properly type page component props in App Router:

import { PageProps } from 'next';

export default function Page({ params, searchParams }: PageProps) {
  // params and searchParams are properly typed
}

This ensures type safety for route params and search params without manual type definitions.

Client-Side State Preservation

When the cacheComponents flag is enabled in next.config.js, Next.js uses React's <Activity> component to preserve component state during client-side navigation.

Enable this experimental feature:

// next.config.js
module.exports = {
  experimental: {
    cacheComponents: true,
  },
};

Component state (form inputs, scroll position, local state) persists when navigating away and back to the same route. This improves user experience for multi-step flows or when users navigate back to partially completed forms.