Client Components

A cup counter that works in the browser

Server Components in Next.js kept everything on the server. Now the tea shop's Mint tea page gets a cup counter: two buttons, and a total that changes as you click. That needs code running in the browser after the page is on the screen, so it needs a Client Component: a component whose code also goes to the browser, where it can keep state and respond to clicks. In Next.js, you start one with "use client" at the top of a file. Why Next.js? used that line for an Add to cart button. That line marks where the client part of the app starts, and everything the file imports goes to the browser with it.

Here is the page, built and run with Next.js 16.4.3. The recorder also opened it in real Chrome and clicked One more twice. The Steps tab is open on the first click.

1"use client";2 3import { useState } from "react";4 5export default function CupPicker({ price }: { price: number }) {6  const [cups, setCups] = useState(1);7  console.log(`CupPicker rendered with ${cups} cup`);8 9  return (10    <p>11      <button onClick={() => setCups(cups - 1)} disabled={cups === 1}>12        One less13      </button>{" "}14      {cups} {cups === 1 ? "cup" : "cups"}: ${cups * price}{" "}15      <button onClick={() => setCups(cups + 1)}>One more</button>16    </p>17  );18}

In app/cup-picker.tsx, line 1 is "use client". Line 6 keeps cups in state, starting at 1, and line 7 prints a message each time CupPicker renders. Lines 11 to 13 are the One less button, disabled at 1 cup. Line 14 shows the count and the total, and line 15 is the One more button. In app/page.tsx, a Server Component, line 8 renders CupPicker with price={3}.

In the Steps tab, the first step opened the page, with one request: the page itself, the document. Each click on One more changed the text, to 2 cups: $6 and then 3 cups: $9, and made no request at all. This click only updates local state, which lives in the browser, and React updated the page there. (A handler that fetches data or calls a Server Function would still send a request.)

Now open the Terminal tab: CupPicker rendered with 1 cup is in next build's output. The Client Component ran on the server too, during the build, and the Browser tab shows the HTML it made: One less 1 cup: $3 One more. (It's printed twice for the reason the last lesson gave: with Cache Components on, the build renders a page twice.) The recording also searched the JavaScript files the page loads: they hold One more, from CupPicker's code, and not Fresh mint leaves, from the page's.

So CupPicker runs in two places. On the server, it renders to HTML. In the browser, React hydrates it: hydration is React running the Client Components again in the browser, matching them to the HTML already on the screen, and attaching their event handlers, so the buttons start to work.

"use client" marks an entry point

Next.js's docs call a file with "use client" an entry point: the place where the client part of the app is entered from the server part. The line between the two parts is called the boundary. Two rules decide what's on the client side of it:

• The directive goes at the very top of the file, before the imports, and it applies to the whole file. A component can't be marked on its own.
• Every file an entry point imports is part of the client too, with or without the directive, and so is everything those files import.

So you don't put "use client" in every file of the client part, only in the files that Server Components render. Here, OrderBox is the entry point. It imports CupCounter from a file without the directive, which imports formatPrice from price.ts. The page imports price.ts too.

"use client";

import { useState } from "react";
import CupCounter from "./cup-counter";

export default function OrderBox({ price }: { price: number }) {
  const [added, setAdded] = useState(false);

  return (
    <section>
      <CupCounter price={price} />
      <button onClick={() => setAdded(true)}>{added ? "Added" : "Add to cart"}</button>
    </section>
  );
}

import { useState } from "react";
import { formatPrice } from "./price";

export default function CupCounter({ price }: { price: number }) {
  const [cups, setCups] = useState(1);

  return (
    <p>
      {cups} {cups === 1 ? "cup" : "cups"}, {formatPrice(cups * price)}{" "}
      <button onClick={() => setCups(cups + 1)}>One more</button>
    </p>
  );
}

In order-box.tsx, line 1 is the directive, line 4 imports CupCounter, and line 11 renders it. In cup-counter.tsx, line 1 imports useState with no directive anywhere in the file, and line 10 is the One more button. Try three versions of who imports CupCounter. Before you click, guess which one fails.

1"use client";2 3import { useState } from "react";4import CupCounter from "./cup-counter";5 6export default function OrderBox({ price }: { price: number }) {7  const [added, setAdded] = useState(false);8 9  return (10    <section>11      <CupCounter price={price} />12      <button onClick={() => setAdded(true)}>{added ? "Added" : "Add to cart"}</button>13    </section>14  );15}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content

In the first version, the recording searched the page's JavaScript. It holds One more, which is only in cup-counter.tsx, and Free today, which is only in price.ts: a text the page never shows, because the price is never 0. Neither file has the directive; they went to the browser because order-box.tsx imports them. The page's own text, Fresh mint leaves, isn't there.

In the second version, the page imports cup-counter.tsx itself. It's the same file, but now a Server Component imports it, so it's part of the server, and its useState stops the build. The import trace under the error shows the path: Server Component: ./app/cup-counter.tsx ./app/page.tsx. In the third version, cup-counter.tsx has its own directive, so it's an entry point too, and the page can render it.

A file can be on both sides. The page and CupCounter both import price.ts, so Next.js builds it once for the server and once for the browser. Only props cross the boundary as data: the page gives OrderBox price={3}, and like every prop from a Server Component, it travels in the RSC payload: React's own description of what the Server Components rendered, with the props they pass to Client Components. Which values can cross, and how to put Server Components inside Client Components, is the next lesson of this stage.

State, Effects and event handlers

Past the boundary, you have all of React: state, event handlers, Effects, refs, context, custom hooks, and the browser's own APIs, like window and localStorage. CupPicker used state and event handlers. An Effect runs after React has put the component on the screen, and only in the browser, which makes it the place to read data that only the browser has.

Here the Mint tea page gets a Save for later button that remembers the choice in localStorage: a small store the browser keeps for each site, which survives a reload. The recorder opened the page, clicked the button, then opened the page again. The Steps tab is open on the last step.

1"use client";2 3import { useEffect, useState } from "react";4 5export default function SaveButton({ id }: { id: string }) {6  const [saved, setSaved] = useState(false);7 8  useEffect(() => {9    setSaved(localStorage.getItem("saved-tea") === id);10  }, [id]);11 12  function save() {13    localStorage.setItem("saved-tea", id);14    setSaved(true);15  }16 17  return (18    <button onClick={save} disabled={saved}>19      {saved ? "Saved" : "Save for later"}20    </button>21  );22}

In app/save-button.tsx, line 6 starts saved at false. Lines 8 to 10 are an Effect: once the button is on the screen, it reads localStorage and sets saved. Lines 12 to 15 are save, which the onClick on line 18 calls: it stores Mint tea's id and sets saved to true. Line 19 shows Saved or Save for later.

In the Steps tab, the first step shows Save for later. The click changed it to Saved and made no request. The last step opened the page again: a whole new page load, one document request, and the button says Saved. The server didn't know about the saved tea. Its HTML, in the Network tab, says Save for later, the same for every visitor. The Effect changed it, in the browser, after hydration.

Client Components still render on the server

"Client" doesn't mean "only in the client". Next.js's docs say a Client Component runs on the server and in the browser. On a first visit, it renders on the server into the HTML, during the build or for the request. Then React renders it again in the browser while it hydrates. The docs add that after a client-side navigation, like a click on a Link, the router gets only the RSC payload, and Client Components render in the browser alone. Step through the first visit to the Mint tea page, then the click:

After step 3 of Opening the page, the visitor sees the buttons, but clicking them does nothing until step 5. React runs only CupPicker in the browser: MintTeaPage is a Server Component, and it never hydrates. Each row below is one piece of CupPicker or SaveButton: what it does during the server render, and what it does in the browser.

So the code that runs while a Client Component renders must work in both places, and give the same result in both. Try three places for SaveButton to read localStorage. Before you click, guess which one the build stops.

1"use client";2 3import { useEffect, useState } from "react";4 5export default function SaveButton({ id }: { id: string }) {6  const [saved, setSaved] = useState(false);7 8  useEffect(() => {9    setSaved(localStorage.getItem("saved-tea") === id);10  }, [id]);11 12  function save() {13    localStorage.setItem("saved-tea", id);14    setSaved(true);15  }16 17  return (18    <button onClick={save} disabled={saved}>19      {saved ? "Saved" : "Save for later"}20    </button>21  );22}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...✓ Generating static pages (3/3)  Finalizing page optimization ... Route (app)┌ ○ /└ ○ /_not-found ○  (Static)  prerendered as static content

The Effect version works, as above. The second version reads localStorage on line 6, while the component renders. The build renders it on the server, where localStorage doesn't exist, and stops with ReferenceError: localStorage is not defined. The third version skips it on the server with typeof window !== "undefined", so the build passes. But a visitor who saved Mint tea gets HTML that says Save for later, and the browser's first render says Saved. In its Steps tab, the last step logged Minified React error #418. That's the short form React uses in production for "Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client." React threw away that part of the HTML and rendered it again in the browser. The Effect version avoids the problem: its first render matches the HTML, and the Effect changes it afterwards. (Hydration, in the React course, shows what React checks.)

Keep the boundary low

Every "use client" file pulls its imports into the browser, so the higher in the component tree you put it, the more goes with it. Put it on the small parts that need the browser, the leaves of the tree, and keep the rest on the server. Here is a Green tea page two ways: the whole page as a Client Component, or only its Add to cart button.

1"use client";2 3import { useState } from "react";4import { teas } from "./data";5 6export default function GreenTeaPage() {7  const tea = teas.find((item) => item.id === "green")!;8  const [added, setAdded] = useState(false);9 10  return (11    <main>12      <h1>{tea.name}</h1>13      <p>{tea.about}</p>14      <button onClick={() => setAdded(true)}>{added ? "Added" : "Add to cart"}</button>15    </main>16  );17}

Both pages look the same in the Browser tab, and both were prerendered as ○ /, with the same content in their HTML. The difference is in the JavaScript the browser downloads, which the page doesn't show. The recording searched each version's JavaScript for three texts. Each row is one text: is it in that version's JavaScript?

With the whole page as a Client Component, data.ts went to the browser, with Lemon tea's description that this page never shows. With only the button, neither description is in the JavaScript; the one the page shows arrives only as rendered text. Each row below compares the two versions:

Components from packages without the directive

Components from npm packages follow the same rule. A package whose components need the browser should start their files with "use client", and Next.js's own Link does: you render it from Server Components all the time. Some packages don't, often because they were written before Server Components existed.

Here, acme-rating stands in for one: a small package written for this lesson, placed in the project's node_modules folder the way npm installs one. Its index.js uses useState and has no directive. Packages ship plain JavaScript, so it calls createElement instead of using JSX. Try rendering it from the page, then through a wrapper:

1import { Rating } from "acme-rating";2 3export default function MintTeaPage() {4  return (5    <main>6      <h1>Mint tea</h1>7      <Rating label="Your rating" />8    </main>9  );10}

$ next build▲ Next.js 16.4.3 (Turbopack)- Cache Components enabled- Partial Prefetching enabled   Creating an optimized production build ...✓ Compiled successfully  Running TypeScript ...  Finished TypeScript ...  Collecting page data ...Error occurred prerendering page "/". Read more: https://nextjs.org/docs/messages/prerender-errorTypeError: (0 , c.useState) is not a function or its return value is not iterable    at ignore-listed frames {  digest: '3028760187'}Export encountered an error on /page: /, exiting the build.⨯ Next.js build worker exited with code: 1 and signal: null

Rendered by the page, the package's code runs as part of a Server Component, with the build of React made for Server Components, which has no useState. The prerender stops with TypeError: (0 , c.useState) is not a function or its return value is not iterable. That's less clear than the message for your own files, which Next.js checks as it compiles them; this package's file got no such message. The fix is a wrapper of your own: app/rating.tsx has "use client" on line 1, imports Rating on line 3 and exports it again on line 5. Now your file is the entry point, and the package comes in as one of its imports. In the wrapper version's Steps tab, clicking 2 stars changes the rating to 2 of 3.

Where does "use client" go?

Put "use client" on the files that a Server Component renders and that need the browser. The files they import don't need it. Sort these files from this lesson:

Every card matches a recording in this lesson. The page built without a directive, cup-counter.tsx worked without one while order-box.tsx imported it, and the wrapper and the Save for later button started the client part where the page rendered them.

Common mix-ups

• "A Client Component renders only in the browser." No. It renders on the server first, into the HTML: CupPicker's message is in next build's output, and its buttons are in the page.
• "Every file in the client part needs "use client"." No. Only the entry points that Server Components render. cup-counter.tsx had none.
• "A file without the directive stays on the server." No. If a client file imports it, it goes to the browser: Free today, from price.ts, was in the page's JavaScript.
• "Making the whole page a Client Component costs nothing." No. Everything it imports goes to the browser, like all three teas' descriptions. The page can no longer be async, and it must not read secrets: its code goes to the browser, and its render on the server can put what it reads into the HTML.
• "Every click in a Client Component sends a request." No. A click that only updates local state, like One more, sent none. A handler sends one only when it fetches something or calls a Server Function.
• "A typeof window check makes browser-only code safe while rendering." No. The server and the browser then render different things, and React logs a hydration error and renders that part again.

Practice exercises

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

import { useState } from "react";
import { formatPrice } from "./price";

export default function CupCounter({ price }: { price: number }) {
  const [cups, setCups] = useState(1);

  return (
    <p>
      {cups} {cups === 1 ? "cup" : "cups"}, {formatPrice(cups * price)}{" "}
      <button onClick={() => setCups(cups + 1)}>One more</button>
    </p>
  );
}

"use client";

import { useState } from "react";

export default function CupPicker({ price }: { price: number }) {
  const [cups, setCups] = useState(1);
  console.log(`CupPicker rendered with ${cups} cup`);

  return (
    <p>
      <button onClick={() => setCups(cups - 1)} disabled={cups === 1}>
        One less
      </button>{" "}
      {cups} {cups === 1 ? "cup" : "cups"}: ${cups * price}{" "}
      <button onClick={() => setCups(cups + 1)}>One more</button>
    </p>
  );
}

"use client";

import { useState } from "react";

export default function SaveButton({ id }: { id: string }) {
  const [saved, setSaved] = useState(localStorage.getItem("saved-tea") === id);

  function save() {
    localStorage.setItem("saved-tea", id);
    setSaved(true);
  }

  return (
    <button onClick={save} disabled={saved}>
      {saved ? "Saved" : "Save for later"}
    </button>
  );
}

"use client";

import { useEffect, useState } from "react";

export default function SaveButton({ id }: { id: string }) {
  const [saved, setSaved] = useState(false);

  useEffect(() => {
    setSaved(localStorage.getItem("saved-tea") === id);
  }, [id]);

  function save() {
    localStorage.setItem("saved-tea", id);
    setSaved(true);
  }

  return (
    <button onClick={save} disabled={saved}>
      {saved ? "Saved" : "Save for later"}
    </button>
  );
}

import { useState } from "react";
"use client";

export default function CupPicker({ price }: { price: number }) {
  const [cups, setCups] = useState(1);
  return (
    <button onClick={() => setCups(cups + 1)}>
      {cups} {cups === 1 ? "cup" : "cups"}: ${cups * price}
    </button>
  );
}

"use client";

import { useState } from "react";

export default function CupPicker({ price }: { price: number }) {
  const [cups, setCups] = useState(1);
  console.log(`CupPicker rendered with ${cups} cup`);

  return (
    <p>
      <button onClick={() => setCups(cups - 1)} disabled={cups === 1}>
        One less
      </button>{" "}
      {cups} {cups === 1 ? "cup" : "cups"}: ${cups * price}{" "}
      <button onClick={() => setCups(cups + 1)}>One more</button>
    </p>
  );
}

import { Rating } from "acme-rating";

export default function MintTeaPage() {
  return (
    <main>
      <h1>Mint tea</h1>
      <Rating label="Your rating" />
    </main>
  );
}

"use client";

import { Rating } from "acme-rating";

export default Rating;

Check your understanding

For each question, ask where the boundary is, and where each render happens.

Key takeaways

• "use client" at the top of a file marks an entry point: that file, and everything it imports, go to the browser, with or without the directive.
• Put it on the files that Server Components render, not on every file. A file that a Server Component imports is part of the server.
• Client Components can use state, Effects, event handlers and browser APIs. A state update in the browser sends nothing to the server.
• They still render on the server first, into the HTML, and React hydrates them in the browser. Code that runs during render must work on the server and give the same result there; read browser-only data in an Effect.
• Keep the boundary low: make the small interactive parts Client Components, and keep pages, layouts and data on the server.
• Wrap a package's component that lacks the directive in a file of your own that starts with "use client".

Coming next: Composing Server and Client Components. It puts Server Components inside Client Components, and shows which props can cross the boundary.