Linking and Navigating

The Next.js router uses server-centric routing with client-side navigation. It supports instant loading states and concurrent rendering. This means navigation maintains client-side state, avoids expensive re-renders, is interruptible, and doesn't cause race conditions.

There are two ways to navigate between routes:

• <Link> Component
• useRouter Hook

This page will go through how to use <Link>, useRouter(), and dive deeper into how navigation works.

<Link> Component

<Link> is a React component that extends the HTML <a> element to provide prefetching and client-side navigation between routes. It is the primary way to navigate between routes in Next.js.

Usage

To use <Link>, import it from next/link, and pass a href prop to the component:

import Link from 'next/link';

export default function Page() {
  return <Link href="/dashboard">Dashboard</Link>;
}

There are optional props you can pass to <Link>. See the API reference for more information.

Example: Linking to Dynamic Segments

When linking to dynamic segments, you can use template literals and interpolation to generate a list of links. For example, to generate a list of blog posts:

import Link from 'next/link';

export default function PostList({ posts }) {
  return (
    <ul>
      {posts.map((post) => (
        <li key={post.id}>
          <Link href={`/blog/${post.slug}`}>
            {post.title}
          </Link>
        </li>
      ))}
    </ul>
  );
}

useRouter() Hook

The useRouter hook allows you to programmatically change routes inside Client Components.

To use useRouter, import it from next/navigation, and call the hook inside your Client Component:

'use client';

import { useRouter } from 'next/navigation';

export default function Page() {
  const router = useRouter();

  return (
    <button type="button" onClick={() => router.push('/dashboard')}>
      Dashboard
    </button>
  );
}

The useRouter provides methods such as push(), refresh(), and more. See the API reference for more information.

Recommendation: Use the <Link> component to navigate between routes unless you have a specific requirement for using useRouter.

How Navigation Works

• A route transition is initiated using <Link> or calling router.push().
• The router updates the URL in the browser’s address bar.
• The router avoids unnecessary work by re-using segments that haven't changed (e.g. shared layouts) from the client-side cache. This is also referred to as partial rendering.
• If the conditions of soft navigation are met, the router fetches the new segment from the cache rather than the server. If not, the router performs a hard navigation and fetches the Server Component payload from the server.
• If created, loading UI is shown from the server while the payload is being fetched.
• The router uses the cached or fresh payload to render the new segments on the client.

Client-side Caching of Rendered Server Components

Good to know: This client-side cache is different from the server-side Next.js HTTP cache.

The new router has an in-memory client-side cache that stores the rendered result of Server Components (payload). The cache is split by route segments which allows invalidation at any level and ensures consistency across concurrent renders.

As users navigate around the app, the router will store the payload of previously fetched segments and prefetched segments in the cache.

This means, for certain cases, the router can re-use the cache instead of making a new request to the server. This improves performance by avoiding re-fetching data and re-rendering components unnecessarily.

Invalidating the Cache

The cache can be invalidated using router.refresh(). For more information, see the API reference. In the future, mutations will automatically invalidate the cache.

Prefetching

Prefetching is a way to preload a route in the background before it's visited. The rendered result of prefetched routes is added to the router's client-side cache. This makes navigating to a prefetched route near-instant.

By default, routes are prefetched as they become visible in the viewport when using the <Link> component. This can happen when the page first loads or through scrolling. Routes can also be programmatically prefetched using the prefetch method of the useRouter() hook.

Static and Dynamic Routes:

• If the route is static, all the Server Component payloads for the route segments will be prefetched.
• If the route is dynamic, the payload from the first shared layout down until the first loading.js file is prefetched. This reduces the cost of prefetching the whole route dynamically and allows instant loading states for dynamic routes.

Good to know:

• Prefetching is only enabled in production.
• Prefetching can be disabled by passing prefetch={false} to <Link>.

Hard Navigation

On navigation, the cache is invalidated and the server refetches data and re-renders the changed segments.

Soft Navigation

On navigation, the cache for changed segments is reused (if it exists), and no new requests are made to the server for data.

Conditions for Soft Navigation

On navigation, Next.js will use soft navigation if the route you are navigating to has been prefetched, and either doesn't include dynamic segments or has the same dynamic parameters as the current route.

For example, consider the following route that includes a dynamic [team] segment: /dashboard/[team]/*. The cached segments below /dashboard/[team]/* will only be invalidated when the [team] parameter changes.

• Navigating from /dashboard/team-red/* to /dashboard/team-red/* will be a soft navigation.
• Navigating from /dashboard/team-red/* to /dashboard/team-blue/* will be a hard navigation.

Back/Forward Navigation

Back and forward navigation (popstate event) has a soft navigation behavior. This means, the client-side cache is re-used and navigation is near-instant.

Focus and Scroll Management

By default, Next.js will set focus and scroll into view the segment that's changed on navigation. The importance of this accessibility and usability feature will be more apparent when advanced routing patterns are implemented.

Good to know: Next.js used to wrap each segment in a div element to achieve this behavior. This is now fixed as on the latest Next.js canary. Update to next@canary to get the latest fixes.

Next Steps