Context Providers on the Client

A theme toggle must reach a header button and a card grid four levels down. The value changes rarely and nearly everything reads it — the textbook case for Context. The problem is Next.js: the pages fetching from the database have to stay Server Components, while the provider's useState demands 'use client'. The two coexist through the {children} pass-through pattern, the single most reused structural snippet in App Router projects.

The provider file is an ordinary client component:

// app/theme-provider.tsx
'use client';

import { createContext, useContext, useMemo, useState } from 'react';

type Theme = 'light' | 'dark';
type ThemeCtx = { theme: Theme; toggle: () => void };

const ThemeContext = createContext<ThemeCtx | null>(null);

export function ThemeProvider({ children }: { children: React.ReactNode }) {
  const [theme, setTheme] = useState<Theme>('light');

  const value = useMemo<ThemeCtx>(
    () => ({
      theme,
      toggle: () => setTheme((t) => (t === 'light' ? 'dark' : 'light')),
    }),
    [theme]
  );

  return <ThemeContext.Provider value={value}>{children}</ThemeContext.Provider>;
}

export function useTheme() {
  const ctx = useContext(ThemeContext);
  if (!ctx) throw new Error('useTheme must be used within ThemeProvider');
  return ctx;
}

The root layout — which stays a Server Component — mounts it:

// app/layout.tsx — no directive; remains a Server Component
import { ThemeProvider } from './theme-provider';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang='en'>
      <body>
        <ThemeProvider>{children}</ThemeProvider>
      </body>
    </html>
  );
}

And any page inside keeps its async server fetching untouched:

// app/page.tsx — still async, still a Server Component
export default async function Home() {
  const posts = await db.post.findMany();
  return <PostGrid posts={posts} />;
}

Why this works: children is a slot of already-rendered content, not something the provider produces. The server renders the entire tree below the layout — including your async page and everything it fetched — into the RSC payload. The provider receives that output as its children prop and drops it into its own JSX without re-creating any of it. Server content stays server content; only the provider module and its imports join the client bundle, because the directive applies per module. Your server data path from Global Client State with Zustand — fetch where the data lives, pass props — is unchanged; this boundary changes who wraps whom, not who fetches what.

Three details make the snippet production-grade. First, the context is created with a null default and the exported hook throws when it is missing, so a provider that gets accidentally removed produces one clear error at the first consumer instead of silently rendering undefined. Second, the prop type is children: React.ReactNode — the widest possible, because whatever the server hands down must cross through untouched. Third, the value is memoized, which the next chapter justifies; the 'use client' directive sits at the top of the provider file, never in the layout.

The shape generalizes. Session providers, query clients, i18n bundles, feature-flag contexts — all use the same file. With several of them, compose once in a single client module so the layout stays readable:

// app/providers.tsx
'use client';

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <SessionProvider>
      <ThemeProvider>
        <QueryProvider>{children}</QueryProvider>
      </ThemeProvider>
    </SessionProvider>
  );
}

One server-rendered <Providers>{children}</Providers> in the layout now boots the whole client-side dependency tree while every page under it stays server-rendered. Each wrapper still follows its own rules: the memoized value and the placement scope from the chapters below apply per provider, not just to the outermost one.

Call toggle and the provider rerenders. Three populations of components are affected differently, and explaining the difference cleanly is what separates a passing answer from a strong one in an interview.

Consumers rerender — always. Every component that called useContext on this context re-runs, sees the new value, and re-renders. That is the contract: context has no selectors, no partial subscription. It is why Global Client State with Zustand exists for high-frequency values, and why Context is reserved for low-frequency, app-wide ones.

The children subtree does not rerender. This surprises people. The children elements crossing the boundary were created by the server; when the provider re-renders, its JSX places the same element references back into the tree, and React bails out of re-rendering any subtree whose element identity is unchanged. Wrapping a large server-rendered tree in a provider is therefore cheap even when the provider's state changes — the expensive server output is reused as-is, and only actual context consumers inside it re-render.

The provider's own JSX beyond the children slot re-renders with it, which is negligible.

Now the detail that decides whether "only consumers" stays true in practice: a context value must be memoized. This line is the classic mistake:

// wrong: a new object identity on every provider render
<ThemeContext.Provider value={{ theme, toggle }}>

Every provider rerender — including ones where theme did not change — hands consumers a fresh object, so useContext's reference comparison always fails and all consumers rerender regardless. The fix is the useMemo you saw in the provider file:

const value = useMemo(() => ({ theme, toggle }), [theme]);

With the value memoized on [theme], a provider rerender that does not change the theme notifies nobody.

When half the app needs only the actions (which are referentially stable) and only some components read the changing value, split the context in two:

const ThemeStateContext = createContext<Theme>('light');  // changes with theme
const ThemeActionsContext = createContext({ toggle });    // stable forever

Components that toggle without reading subscribe to the actions context and never rerender on a theme change. This is the Context-shaped version of selector granularity:

function ThemeToggle() {
  // subscribes only to the stable actions context
  const toggle = useContext(ThemeActionsContext);
  return <button onClick={toggle}>Toggle theme</button>;
}

In React 19 projects with the Compiler enabled, the useMemo bookkeeping is inserted for you; without it, the memoization is your job, and the exhaustive-deps lint rule is the safety net that flags a dependency you forgot.

A production detail for the value context: the server cannot compute it (hooks do not exist there), so the initial value is whatever the provider's useState starts with. Passing that seed from the server layout — <ThemeProvider initialTheme={theme}> — is how you keep the server HTML and the client's first render in agreement, which is where the pitfalls chapter picks up.

Finally, scope the tool choice deliberately — Context is one row of a small decision table:

And a hard boundary: Server Components cannot consume context — hooks do not exist for them. If the server-rendered HTML itself needs the value (the right theme class on <html>, a localized string), the server reads the source of truth (a cookie, the request) and passes it down as a serializable prop, which is exactly the hydration-consistency move the next chapter builds on.

The provider works perfectly — until the user toggles the theme, clicks a nav link, and clicks Back. Theme: reset. The bug is placement. You mounted <ThemeProvider> inside app/page.tsx instead of the layout, and pages are components too: client-side navigation unmounts the page component, taking the provider's useState with it. The rule follows from the lifetime model in Local State with useState and useReducer: stateful providers belong in layouts, because layouts persist across navigations within their segment. A provider in the root layout survives every route change in the app.

Placement has a scope, and the scope is the layout tree:

The generalization: the provider must sit at the lowest common ancestor of all its consumers. Note that leaving a route group is itself a layout boundary — a wizard provider in app/(checkout)/layout.tsx survives moving between checkout steps but resets on a detour to the marketing section, which is usually the scope you want. Put it in one of two sibling pages and the other cannot read it; put it at the root when only a dashboard section needs it and you have paid the wiring cost (and the client-bundle cost of its imports) globally. A section-scoped provider in a nested layout is the right middle ground for state like a multi-step wizard scoped to /dashboard/*.

Four more failures that show up in review:

Forgetting 'use client' in the provider file. The build stops with an error like createContext only works in Client Components. The directive belongs on the provider module — the layout that mounts it must not have it.

Non-serializable props across the boundary. A Server Component layout can pass plain serializable props into the provider — and that is how you seed state from the server — but functions and class instances cannot cross the client boundary. Pass data, not behavior: <ThemeProvider initialTheme={cookieTheme}> works; passing a server-defined callback does not.

Hydration mismatch on the initial value. If the server renders class='dark' from a cookie while the provider's useState starts at 'light', the first client render disagrees with the server HTML and hydration fails. The fix is to make the server the seed: the layout reads the cookie and hands it over.

// app/layout.tsx (server)
const theme = (await cookies()).get('theme')?.value ?? 'light';
// ...
<ThemeProvider initialTheme={theme}>{children}</ThemeProvider>

// provider: accept the seed, keep it out of the server's way
export function ThemeProvider({
  initialTheme,
  children,
}: {
  initialTheme?: Theme;
  children: React.ReactNode;
}) {
  const [theme, setTheme] = useState<Theme>(initialTheme ?? 'light');
  // ...
}

High-frequency updates through context. A controlled search input whose value lives in app-wide context rerenders every consumer per keystroke. Values that change fast belong in local state or a store; Context serves values that change slowly and are read together.

Remember that even a correctly placed provider holds client memory — a reload resets it, cookie-seeded values excepted. For a wizard whose draft must survive a reload, persist to localStorage with the skipHydration dance from the Zustand topic, or write the draft to the server. And once the provider plumbing is in place, the state it often carries next is a twenty-field form — which is where Complex Forms with react-hook-form takes over.