Linking and navigating

A click that swaps only the page

In Layouts and pages, a tea layout kept its counter while the visitor clicked from Green tea to Mint tea. That worked because the menu used Link, from next/link. This lesson is about Link itself, and everything around a click: what Next.js loads before it, what the click asks for, how to navigate from your own code, and where the scroll and the keyboard focus go afterwards.

Here is the tea shop with a Link to /teas. The teas page has a part, the stock, that the server makes for each request and that takes a moment. A click needs the page's JavaScript running, so this example was also opened in real Chrome against next start, and Chrome took four steps: open /, click Teas, wait for the stock, click Home. Open the Steps tab and pick each step: you see the page after it, and the requests the page made during it.

1import Link from "next/link";2 3export const metadata = { title: "Tea shop" };4 5export default function RootLayout({ children }: LayoutProps<"/">) {6  return (7    <html lang="en">8      <body>9        <nav>10          <Link href="/">Home</Link> <Link href="/teas">Teas</Link>11        </nav>12        {children}13      </body>14    </html>15  );16}

Line 10 of app/layout.tsx has two links. In the Network tab, the HTML of / has them as plain <a href="/"> and <a href="/teas"> elements, so they work even before any JavaScript runs. Once it runs, Next.js handles their clicks. When the new page has the same root layout as the current one (the layout that renders <html> and <body>), as every page in this shop does, it changes the address and swaps only the page part, without loading a new HTML page. That's a client-side navigation.

The exception: an app can have more than one root layout, one per group of pages. A Link to a page under a different root layout loads a whole new HTML page, because the <html> itself changes. Route groups and private folders recorded one. Every example in this lesson has a single root layout.

Now read the steps:

1. Open /. One document request, for the HTML page. Then, before anyone clicked, fetches for /teas with the header next-router-prefetch. That's prefetching: loading a linked page in the background, before the click. What it loads is the page's static shell: the parts that don't wait for a request, like the heading and the Checking stock… fallback.
2. Click Teas. The address is /teas, and the page shows Our teas and Checking stock…. There's one fetch, without the prefetch header: the router asking for the part it didn't have, the stock. Its answer is text/x-component, an RSC payload: the data React uses to draw what the Server Components rendered. (How Next.js works showed one.)
3. Wait for the stock. In stock: 12 boxes takes the place of Checking stock…, from the same request.
4. Click Home. No requests at all: the home page was prefetched when the page opened, and nothing on it is made for each request.

The Link component

Link is a component that comes with Next.js. You import it with import Link from "next/link", as on line 1 of the layout, and give it an href. Anything an <a> takes, like className or aria-current, passes through to the <a> it renders. It has a few props of its own. Each row is one prop: what it does, and what happens when you leave it out.

Use Link for every page of your own app. For another website, a plain <a> is right: there's nothing of yours to prefetch or keep.

Prefetching what's on the screen

New Next.js 16 projects turn on partial prefetching in next.config.ts, with partialPrefetching: true; Next.js 16.3 added it, and 16.4 made it part of every new app. With it, a Link prefetches the linked route's App Shell: the parts of the page that don't depend on the link's address. When the route reads nothing about the visitor, that's its static shell, made during the build, the same one a direct visit gets as HTML; when it reads cookies, the App Shell is rendered for each visitor's session (Instant navigations and partial prefetching records both). One App Shell serves every link to that route. The parts made for each request, like the stock, stream in after the click.

Compare three ways to link to /teas. Each version took the same steps in Chrome. Pick a version, then look at the requests of step 1 (opening /) and step 2 (the click).

1import Link from "next/link";2 3export const metadata = { title: "Tea shop" };4 5export default function RootLayout({ children }: LayoutProps<"/">) {6  return (7    <html lang="en">8      <body>9        <nav>10          <Link href="/">Home</Link> <Link href="/teas">Teas</Link>11        </nav>12        {children}13      </body>14    </html>15  );16}

With Link, step 1 has the prefetches for /teas, and the click asks only for the stock. With prefetch={false}, step 1 has no request for /teas; the router asks for the page at the click. With a plain <a>, there's no prefetch and no client-side navigation: the click is a document request, a whole new page.

Next.js doesn't prefetch every link on the page at once. It prefetches a link when the link enters the viewport, the part of the page on the screen. This home page has a Gift boxes link far down, below a tall empty <div> that stands in for a long page:

1import Link from "next/link";2 3export default function HomePage() {4  return (5    <main>6      <h1>Tea shop</h1>7      <p>Fresh tea, sent to your door.</p>8      <div style={{ height: 1600 }} />9      <Link href="/gift-boxes">Gift boxes</Link>10    </main>11  );12}

Step 1 prefetches / and /teas, the links in the layout, but not /gift-boxes. Step 2 scrolls to the bottom, and the prefetch for /gift-boxes appears. Step 3 clicks it, with no request at all: the page is prerendered as static content, so its shell is the whole page.

Three more facts from the Link reference on nextjs.org:

• Production only. Prefetching happens after next build and next start; in next dev, links don't prefetch, so test this in a production build.
• Hover. A prefetch doesn't last forever. If what was prefetched has expired by the time the visitor hovers over the link, Next.js prefetches it again.
• Turning it off. prefetch={false} turns off both: no prefetch when the link enters the viewport, and none on hover. A list of hundreds of links, like an endless list of orders, can use it so the browser doesn't fetch pages nobody will open.

Showing which page the visitor is on

A menu usually marks the link of the current page, so visitors know where they are. The layout can't know the path, as the previous lesson showed, so the menu moves into a Client Component that calls usePathname:

1"use client";2 3import Link from "next/link";4import { usePathname } from "next/navigation";5 6const links = [7  { href: "/", label: "Home" },8  { href: "/teas", label: "Teas" },9  { href: "/cart", label: "Cart" },10];11 12export default function NavLinks() {13  const pathname = usePathname();14  return (15    <ul>16      {links.map((link) => {17        const active = link.href === "/" ? pathname === "/" : pathname === link.href || pathname.startsWith(`${link.href}/`);18        return (19          <li key={link.href}>20            <Link href={link.href} aria-current={active ? "page" : undefined}>21              {link.label}22            </Link>23          </li>24        );25      })}26    </ul>27  );28}

Line 13 reads the path. Line 17 decides whether each link is the active one: / only on the home page, and any other link on its own path or a path below it. The / after link.href matters: without it, /teas would also match an address like /teaspoons. Line 20 sets aria-current="page" on the active link. It tells screen readers which link is the current page, and your CSS can style it with [aria-current="page"].

Pick /teas/green in the Browser tab: Teas is bold, because the recorded page marked it, and the Network tab shows aria-current="page" in the HTML. The server already rendered the right link, since usePathname works while Next.js renders a Client Component on the server too. The Steps tab shows it moving in Chrome: Home after step 1, Teas after the click on Teas, and still Teas on /teas/green.

Navigating from code with useRouter

Sometimes your code, not a link, decides where to go: after a button press, or when something finishes. For that, Client Components call useRouter from next/navigation. The router it returns has a few methods:

• router.push(href) navigates to href, adding an entry to the browser's history, like a Link click.
• router.replace(href) navigates too, but replaces the current history entry, so Back skips the page you left.
• router.refresh() asks the server for the current page again, and merges the new output of its Server Components into the page, keeping the state in the browser.
• router.back() goes to the previous history entry, like the browser's Back button.

The cart and checkout below use all four. Chrome took eight steps; read the code first, then the steps.

1"use client";2 3import { useState } from "react";4import { useRouter } from "next/navigation";5 6export default function CartButtons() {7  const router = useRouter();8  const [note, setNote] = useState("");9 10  function addMint() {11    document.cookie = "cart=mint; path=/";12    router.refresh();13  }14 15  return (16    <div>17      <label>18        Note for the driver <input value={note} onChange={(event) => setNote(event.target.value)} />19      </label>20      <p>21        <button onClick={addMint}>Add a mint tea</button> <button onClick={() => router.push("/checkout")}>Checkout</button>22      </p>23    </div>24  );25}

In app/cart/cart-buttons.tsx, line 7 gets the router. addMint stores a cookie on line 11 and calls router.refresh() on line 12. In step 3, the cart says In your cart: Mint tea: the server ran CartItem again, and it read the new cookie. The note typed in step 2, Leave it at the door, is still in its field, because note is state in the browser and the refresh kept it. The step's requests show one fetch for /cart, not a document: no page reload.

Line 21's Checkout button calls router.push("/checkout"), and step 4 is on /checkout. It made one fetch: nothing had prefetched the checkout, because no Link pointed to it. (Your code can warm a page up with router.prefetch(href).) In app/checkout/checkout-buttons.tsx, Back to cart calls router.back(), and step 5 is on /cart again, with the note still there. Place order calls router.replace("/thanks"). Then step 8 presses the browser's Back button, and the address is /cart, not /checkout: the replace swapped the checkout's entry in the history for /thanks.

Pending links and onNavigate

Next.js 15.3 added two tools for the moment of a click. The first is useLinkStatus, a hook from next/link. A component inside a Link calls it, and gets pending: true after the click, while the router waits for the page and the address hasn't changed yet, and false otherwise. Use it for a small hint that the click was heard.

To see it, the Orders link below doesn't prefetch, and Chrome's network was made slow before the click, the way a weak phone signal is.

1import Link from "next/link";2import PendingHint from "./pending-hint";3 4export const metadata = { title: "Tea shop" };5 6export default function RootLayout({ children }: LayoutProps<"/">) {7  return (8    <html lang="en">9      <body>10        <nav>11          <Link href="/">Home</Link>{" "}12          <Link href="/orders" prefetch={false}>13            Orders14            <PendingHint />15          </Link>16        </nav>17        {children}18      </body>19    </html>20  );21}

In the first version, app/pending-hint.tsx calls useLinkStatus() and shows (opening…) while pending is true; line 14 of the layout puts it inside the Orders link. Step 3 caught it: the address is still /, the old page is still on the screen, and the link says Orders (opening…). In step 4, the orders page is there and the hint is gone. In the second version, the link prefetched the page while the network was still fast, and the click needs no request: no pending moment, no hint. So the hook helps most when a link can't prefetch, or the prefetch hasn't finished.

The second tool is onNavigate, a prop of Link. Next.js calls it when the click starts a client-side navigation, with an event whose preventDefault() stops it. The feedback form uses it so visitors don't lose what they wrote:

1"use client";2 3import Link from "next/link";4import { useState } from "react";5 6export default function FeedbackForm() {7  const [text, setText] = useState("");8  const [warning, setWarning] = useState("");9  return (10    <div>11      <label htmlFor="feedback">Your feedback</label>12      <textarea id="feedback" value={text} onChange={(event) => setText(event.target.value)} />13      <p>14        <Link15          href="/"16          onNavigate={(event) => {17            if (text) {18              event.preventDefault();19              setWarning("Send or clear your feedback before you leave.");20            }21          }}22        >23          Back to the shop24        </Link>25      </p>26      {warning && <p>{warning}</p>}27    </div>28  );29}

Lines 16 to 21 are the handler. When text isn't empty, line 18 stops the navigation and line 19 shows a warning. In step 3, after Lovely mint tea was typed, the click on Back to the shop left the address at /feedback, with the warning under the link. In step 4 the field was cleared, and in step 5 the same click went to /. onNavigate isn't onClick: the docs say it doesn't run when the click opens a new tab, or for a link to another website, because those aren't client-side navigations.

Scroll and focus after a navigation

A whole page load starts at the top of the new page. A client-side navigation keeps the same window, so Next.js decides where the scroll goes. Its rule: if the top of the new page is already in view, it doesn't scroll; if not, it scrolls to it. The teas page below is long, with the Green tea link at the bottom, and the window is 640 pixels tall. Chrome scrolled down, then clicked.

1import Link from "next/link";2 3export default function TeasPage() {4  return (5    <main>6      <h1>Our teas</h1>7      <div style={{ height: 1600 }} />8      <Link href="/teas/green">Green tea</Link>9    </main>10  );11}

Before the click, step 2 is 1092 px down, as far as the page goes. After it, with a plain Link, step 3 is at 0 px: the top of the Green tea page was out of view, so Next.js scrolled to it. With scroll={false}, step 3 is still at 1092 px, and the heading is off the screen. router.push(href, { scroll: false }) does the same from code. Use it when the new page should open where the visitor was, like a list whose filter changed.

Now the keyboard focus: the element that gets the keys the visitor presses, like Tab or Enter. Next.js 16.4.3 doesn't move it after a navigation; a comment in its scroll handler says it leaves focus untouched on purpose. So the recordings show two cases. In step 3 of the first version, the clicked Green tea link was part of the old page, which Next.js hid, so nothing has focus. In step 4, the clicked link, Teas, is in the layout, which stayed, so it still has focus.

Screen reader users still hear that the page changed. Next.js adds a hidden route announcer to every page: a part that screen readers read out, which says the new page's title after a navigation, or its <h1> if it has no title. The Green tea page sets its own title, and step 3 shows the announcement Green tea; after the click on Teas, it says Tea shop. You can read it in app-router-announcer.tsx.

Choosing how to navigate

Each row is one way to move the visitor, when it fits, and what it does.

A rule of thumb: if the visitor clicks something that goes somewhere, it's a Link. If your code decides, it's useRouter. Moving the visitor on the server, before a page renders, is a redirect; the lesson on redirects comes later in the Routing and navigation stage: Redirects. Sort these:

Common mix-ups

• "Link doesn't render a real link." No. It renders an <a href>, as the recorded HTML shows.
• "A Link prefetches the whole page." No. With partial prefetching, it prefetches the static shell. The stock came only after the click.
• "Every link on the page is prefetched as soon as it loads." No. Only links in or near the viewport; Gift boxes was prefetched after the scroll.
• "Prefetching works in next dev." No. It runs only in production, as the docs say. Test it with next build and next start.
• "router.refresh() reloads the page." No. It fetches the server's new output and keeps the state in the browser: the note stayed.
• "Next.js moves focus to the new page." No. It leaves focus alone, and the route announcer tells screen readers about the new page.

Practice exercises

These exercises are about Next.js projects, which can't run inside this page. Answer first, then use the hints.

import Link from "next/link";

export const metadata = { title: "Tea shop" };

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en">
      <body>
        <nav>
          <Link href="/">Home</Link> <Link href="/teas">Teas</Link>
        </nav>
        {children}
      </body>
    </html>
  );
}

import Link from "next/link";

export const metadata = { title: "Tea shop" };

export default function RootLayout({ children }: LayoutProps<"/">) {
  return (
    <html lang="en">
      <body>
        <nav>
          <Link href="/">Home</Link> <Link href="/teas" prefetch={false}>Teas</Link>
        </nav>
        {children}
      </body>
    </html>
  );
}

"use client";

import Link from "next/link";
import { usePathname } from "next/navigation";

const links = [
  { href: "/", label: "Home" },
  { href: "/teas", label: "Teas" },
  { href: "/cart", label: "Cart" },
];

export default function NavLinks() {
  const pathname = usePathname();
  return (
    <ul>
      {links.map((link) => {
        const active = link.href === "/" ? pathname === "/" : pathname === link.href || pathname.startsWith(`${link.href}/`);
        return (
          <li key={link.href}>
            <Link href={link.href} aria-current={active ? "page" : undefined}>
              {link.label}
            </Link>
          </li>
        );
      })}
    </ul>
  );
}

"use client";

import { useRouter } from "next/navigation";

export default function CheckoutButtons() {
  const router = useRouter();
  return (
    <p>
      <button onClick={() => router.back()}>Back to cart</button>{" "}
      <button onClick={() => router.replace("/thanks")}>Place order</button>
    </p>
  );
}

"use client";

import { useState } from "react";
import { useRouter } from "next/navigation";

export default function CartButtons() {
  const router = useRouter();
  const [note, setNote] = useState("");

  function addMint() {
    document.cookie = "cart=mint; path=/";
    router.refresh();
  }

  return (
    <div>
      <label>
        Note for the driver <input value={note} onChange={(event) => setNote(event.target.value)} />
      </label>
      <p>
        <button onClick={addMint}>Add a mint tea</button> <button onClick={() => router.push("/checkout")}>Checkout</button>
      </p>
    </div>
  );
}

import Link from "next/link";

export default function TeasPage() {
  return (
    <main>
      <h1>Our teas</h1>
      <div style={{ height: 1600 }} />
      <Link href="/teas/green" scroll={false}>Green tea</Link>
    </main>
  );
}

Check your understanding

For each question, ask what the router already had before the click, and what it had to ask the server for.

Key takeaways

• Link renders an <a href>. Once the page's JavaScript runs, a click to a page under the same root layout becomes a client-side navigation: the address changes, the page part is swapped, and the layouts stay. A page under another root layout loads as a whole new page.
• In production, a Link in the viewport prefetches the linked route's static shell. The click shows it, and the router asks only for the parts made for each request. prefetch={false} waits for the click.
• Mark the current page's link from a Client Component with usePathname and aria-current="page".
• useRouter navigates from code: push adds a history entry, replace swaps it, refresh re-runs the Server Components and keeps browser state, back goes back.
• useLinkStatus shows a link is waiting; onNavigate can stop a navigation.
• Next.js scrolls to the new page when its top is out of view (scroll={false} stops it), leaves focus where it was, and announces the new title to screen readers.

Coming next: Dynamic routes. It replaces the shop's one folder per tea with a single folder that matches every tea, and shows how a page reads which one was asked for.