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.

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.

Examples

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>
  );
}

Checking Active Links

You can use usePathname() to determine if a link is active. For example, to add a class to the active link, you can check if the current pathname matches the href of the link:

"use client";
 
import { usePathname } from "next/navigation";
import { Link } from "next/link";
 
export function Navigation({ navLinks }) {
  const pathname = usePathname();
 
  return (
    <>
      {navLinks.map((link) => {
        const isActive = pathname.startsWith(link.href);
 
        return (
          <Link
            className={isActive ? "text-blue" : "text-black"}
            href={link.href}
            key={link.name}
          >
            {link.name}
          </Link>
        );
      })}
    </>
  );
}

Scrolling to an id

The default behavior of <Link> is to scroll to the top of the route segment that has changed. When there is an id defined in href, it will scroll to the specific id, similarly to a normal <a> tag.

To prevent scrolling to the top of the route segment, set scroll={false} and pass the add a hashed id to href:

<Link href="/#hashid" scroll={false}>
  Scroll to specific id.
</Link>

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

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

Server Actions can be used to revalidate data on-demand by path (revalidatePath) or by cache tag (revalidateTag).

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.

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.

Hard Navigation

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

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.