---
name: react-patterns
description: Provides idiomatic React 18/19 and Next.js App Router patterns covering hooks discipline, composition, state colocation, server/client boundaries, Suspense and error boundaries, forms, data fetching, list keys, effects hygiene, and measurement-first performance work. Use when writing, reviewing, or refactoring React components, custom hooks, or Next.js routes.
---
# React Patterns
React rewards code that keeps render pure, puts state where it is used, and reaches for
optimisation only after measuring. This skill is the checklist for that.
## When to use
- Writing or modifying function components, custom hooks, or component trees.
- Reviewing JSX/TSX diffs.
- Choosing where state should live or how components should compose.
- Working across Server and Client Components in the Next.js App Router.
- Diagnosing slow renders, waterfalls, or oversized bundles.
## Core rules
**Render is a pure function of props and state.** Derive during render; do not store derived values.
```tsx
// Good
function Cart({ items }: { items: CartItem[] }) {
const total = items.reduce((sum, i) => sum + i.price * i.qty, 0);
return {formatMoney(total)};
}
// Bad: an extra render, a chance to desync, and hidden data flow
function Cart({ items }: { items: CartItem[] }) {
const [total, setTotal] = useState(0);
useEffect(() => setTotal(items.reduce((s, i) => s + i.price * i.qty, 0)), [items]);
return {formatMoney(total)};
}
```
**Side effects live in event handlers or `useEffect`, never in the render body.**
**Compose, do not inherit.** `children`, slot props, and compound components cover every case.
**Do not define components inside components.** A new component type on every render remounts
its subtree and loses state.
## Hooks discipline
- Call hooks at the top level only; never inside conditions, loops, or after early returns.
- Every subscription, timer, and listener returns a cleanup.
- Use the functional updater when new state depends on old: `setCount(c => c + 1)`.
- Dependencies are honest: list what the effect reads. If the list is painful, the effect is
doing too much or the value should be a ref or an event handler.
- Extract a custom hook when the same hook sequence appears in two or more components, not before.
- Expensive initial state uses the lazy initialiser: `useState(() => parse(bigInput))`.
## Effects hygiene
Most `useEffect` calls in application code are one of these mistakes:
| You wrote an effect to... | Do this instead |
|---|---|
| Compute a value from props/state | Derive during render (or `useMemo` if measured) |
| Respond to a user action | Put the logic in the event handler |
| Fetch application data | Use a server-state library or RSC (see Data fetching) |
| Reset state when a prop changes | Give the component a `key` tied to that prop |
| Notify a parent of state change | Lift the state, or call the parent's callback in the handler |
| Initialise something once per app | Module-scope guard, not an effect |
Legitimate effects synchronise with something outside React: DOM measurement, subscriptions,
third-party widgets, analytics on mount. Use primitive dependencies (`[id, name]`), not fresh
objects (`[{ id, name }]`).
## State location
```
Used by one component? -> useState inside it
Shared by a parent and a few children? -> lift to the nearest common ancestor
Low-frequency, tree-wide (theme, auth)? -> Context, one context per concern
High-frequency, tree-wide? -> external store (Zustand, Jotai, Redux Toolkit)
Comes from a server? -> server-state library or RSC, not useState
```
Colocate by default. Most pages need neither context nor a global store. Split contexts so a
change to notifications does not re-render every theme consumer. When subscribing to a store,
select the narrowest value (`useStore(s => s.cart.length > 0)`), not the whole object.
## Composition recipes
```tsx
// Slot via children
{content}
// Named slots
} sidebar={}>
// Compound components sharing state through context
ProfileSettings
```
Render props still work but a hook returning the same shape (`useData(id)`) is usually cleaner.
## Lists and keys
- Keys are stable identities from the data (`item.id`), never the array index for lists that
reorder, filter, or insert.
- A `key` change deliberately remounts; use it to reset form state when the edited entity changes.
- Render conditionally with a ternary, not `&&`, when the left side can be `0` or `""`:
`{count > 0 ? {count} : null}`.
- Virtualise (`@tanstack/react-virtual`, `react-window`) once visible rows exceed roughly fifty
with non-trivial content; before that, `content-visibility: auto` on rows is often enough.
## Server / Client boundaries (Next.js App Router)
```tsx
// Server Component: default, async, ships no JS for itself
export default async function ProductPage({ params }: { params: { id: string } }) {
const product = await db.product.findUnique({ where: { id: params.id } });
if (!product) notFound();
return } />;
}
// Client Component: opt in
"use client";
export function AddToCart({ productId }: { productId: string }) {
const [pending, startTransition] = useTransition();
return (
);
}
```
Rules at the boundary:
- Server -> Client: pass serialisable props or `children`. Never a function, class instance, or Date without serialising.
- Client -> Server: call Server Actions from `
);
}
```
Validate on the server with a schema (zod or similar) before touching the database. Use
controlled inputs when the value drives other UI or needs per-keystroke formatting. Multi-step
forms, field arrays, and cross-field validation belong in React Hook Form or TanStack Form.
`useOptimistic` gives instant feedback for mutations that almost always succeed.
## Performance: measure first
Default: do not memoise. Add `useMemo`, `useCallback`, or `React.memo` only when the React
profiler shows a component re-rendering often with unchanged props and a measurable cost.
If the project ships React Compiler, manual memoisation is noise.
When measurement says yes:
- `React.memo` a leaf that is expensive and receives stable props. Hoist default non-primitive
props (`const EMPTY: Item[] = []`) so the memo is not defeated by fresh identities.
- `useMemo` for expensive derivations or objects passed to memoised children; never for `x + 1`.
- `useCallback` with functional updaters so the callback needs no dependencies.
- `startTransition` / `useDeferredValue` to keep typing responsive while expensive UI updates.
- Do not subscribe to store state that is only read inside a callback; read it on call instead.
Bundle and load:
- Import directly (`@/components/Button`), not from barrel files, unless Next.js
`optimizePackageImports` covers the package.
- `next/dynamic` for heavy client-only components; `next/script` with `afterInteractive` or
`lazyOnload` for third-party scripts.
- Keep dynamic import paths statically analysable: no template strings in `import()`.
Rendering:
- Animate wrappers with transforms, not layout properties.
- Inline a tiny script for pre-hydration values (theme) to avoid flicker; use
`suppressHydrationWarning` only on the single leaf that legitimately differs.
## Accessibility baseline
- Semantic elements first (`