React Docs Voice & Style
Universal Rules
- Capitalize React terms when referring to the React concept in headings or as standalone concepts:
- Core: Hook, Effect, State, Context, Ref, Component, Fragment - Concurrent: Transition, Action, Suspense - Server: Server Component, Client Component, Server Function, Server Action - Patterns: Error Boundary - Canary: Activity, View Transition, Transition Type - In prose: Use lowercase when paired with descriptors: "state variable", "state updates", "event handler". Capitalize when the concept stands alone or in headings: "State is isolated and private" - General usage stays lowercase: "the page transitions", "takes an action"
- Product names: ESLint, TypeScript, JavaScript, Next.js (not lowercase)
- Bold for key concepts: state variable, event handler
- Italics for new terms being defined: *event handlers*
- Inline code for APIs:
useState,startTransition,<Suspense> - Avoid: "simple", "easy", "just", time estimates
- Frame differences as "capabilities" not "advantages/disadvantages"
- Avoid passive voice and jargon
Tone by Page Type
| Type | Tone | Example |
|---|---|---|
| Learn | Conversational | "Here's what that looks like...", "You might be wondering..." |
| Reference | Technical | "Call useState at the top level...", "This Hook returns..." |
| Blog | Accurate | Focus on facts, not marketing |
Note: Pitfall and DeepDive components can use slightly more conversational phrasing ("You might wonder...", "It might be tempting...") even in Reference pages, since they're explanatory asides.
Avoiding Jargon
Pattern: Explain behavior first, then name it.
✅ "React waits until all code in event handlers runs before processing state updates. This is called *batching*."
❌ "React uses batching to process state updates atomically."
Terms to avoid or explain:
| Jargon | Plain Language |
|---|---|
| atomic | all-or-nothing, batched together |
| idempotent | same inputs, same output |
| deterministic | predictable, same result every time |
| memoize | remember the result, skip recalculating |
| referentially transparent | (avoid - describe the behavior) |
| invariant | rule that must always be true |
| reify | (avoid - describe what's being created) |
Allowed technical terms in Reference pages:
- "stale closures" - standard JS/React term, can be used in Caveats
- "stable identity" - React term for consistent object references across renders
- "reactive" - React term for values that trigger re-renders when changed
- These don't need explanation in Reference pages (readers are expected to know them)
Use established analogies sparingly—once when introducing a concept, not repeatedly:
| Concept | Analogy |
|---|---|
| Components/React | Kitchen (components as cooks, React as waiter) |
| Render phases | Restaurant ordering (trigger/render/commit) |
| State batching | Waiter collecting full order before going to kitchen |
| State behavior | Snapshot/photograph in time |
| State storage | React storing state "on a shelf" |
| State purpose | Component's memory |
| Pure functions | Recipes (same ingredients → same dish) |
| Pure functions | Math formulas (y = 2x) |
| Props | Adjustable "knobs" |
| Children prop | "Hole" to be filled by parent |
| Keys | File names in a folder |
| Curly braces in JSX | "Window into JavaScript" |
| Declarative UI | Taxi driver (destination, not turn-by-turn) |
| Imperative UI | Turn-by-turn navigation |
| State structure | Database normalization |
| Refs | "Secret pocket" React doesn't track |
| Effects/Refs | "Escape hatch" from React |
| Context | CSS inheritance / "Teleportation" |
| Custom Hooks | Design system |
Common Prose Patterns
Wrong vs Right code:
\`\`\`js
// 🚩 Don't mutate state:
obj.x = 10;
\`\`\`
\`\`\`js
// ✅ Replace with new object:
setObj({ ...obj, x: 10 });
\`\`\`Table comparisons:
| passing a function | calling a function |
| `onClick={handleClick}` | `onClick={handleClick()}` |Linking:
[Read about state](/learn/state-a-components-memory)
[See `useState` reference](/reference/react/useState)Code Style
- Prefer JSX over createElement
- Use const/let, never var
- Prefer named function declarations for top-level functions
- Arrow functions for callbacks that need
thispreservation
Version Documentation
When APIs change between versions:
Starting in React 19, render `<Context>` as a provider:
\`\`\`js
<SomeContext value={value}>{children}</SomeContext>
\`\`\`
In older versions:
\`\`\`js
<SomeContext.Provider value={value}>{children}</SomeContext.Provider>
\`\`\`Patterns:
- "Starting in React 19..." for new APIs
- "In older versions of React..." for legacy patterns