Reference page structure, templates, and writing patterns for src/content/reference/. For components, see /docs-components. For code examples, see /docs-sandpack.
Reference page structure, templates, and writing patterns for src/content/reference/. For components, see /docs-components. For code examples, see /docs-sandpack.
Reference Page Writer
Quick Reference
Page Type Decision Tree
Is it a Hook? Use Type A (Hook/Function)
Is it a React component (<Something>)? Use Type B (Component)
Is it a compiler configuration option? Use Type C (Configuration)
Is it a directive ('use something')? Use Type D (Directive)
Is it an ESLint rule? Use Type E (ESLint Rule)
Is it listing multiple APIs? Use Type F (Index/Category)
Component Selection
For component selection and patterns, invoke /docs-components.
**Key differences from Hook pages:**
- Title uses JSX syntax: `<ComponentName>`
- Uses `#### Props` instead of `#### Parameters`
- Reference heading uses JSX: `` ### `<ComponentName>` ``
---
### Type C: Configuration
**When to use:** Documenting React Compiler configuration options
```mdx
---
title: optionName
---
<Intro>
The `optionName` option [controls/specifies/determines] [what it does].
</Intro>
```js
{
optionName: 'value' // Quick example
}
Reference {/reference/}
optionName {/optionname/}
[Description of the option's purpose]
Type {/type/}
'value1' | 'value2' | 'value3'
Default value {/default-value/}
'value1'
Options {/options/}
'value1' (default): Description
'value2': Description
'value3': Description
Caveats {/caveats/}
[Usage caveats]
---
### Type D: Directive
**When to use:** Documenting directives like 'use server', 'use client', 'use memo'
```mdx
---
title: "'use directive'"
titleForTitleTag: "'use directive' directive"
---
<RSC>
`'use directive'` is for use with [React Server Components](/reference/rsc/server-components).
</RSC>
<Intro>
`'use directive'` marks [what it marks] for [purpose].
```js {1}
function MyComponent() {
'use directive';
// ...
}
Reference {/reference/}
'use directive' {/use-directive/}
Add 'use directive' at the beginning of [location] to [action].
Caveats {/caveats/}
'use directive' must be at the very beginning...
The directive must be written with single or double quotes, not backticks.
[Other placement/syntax caveats]
**Key characteristics:**
- Title includes quotes: `title: "'use server'"`
- Uses `titleForTitleTag` for browser tab title
- `<RSC>` block appears before `<Intro>`
- Caveats focus on placement and syntax requirements
---
### Type E: ESLint Rule
**When to use:** Documenting ESLint plugin rules
```mdx
---
title: rule-name
---
<Intro>
Validates that [what the rule checks].
</Intro>
## Rule Details {/*rule-details*/}
[Explanation of why this rule exists and React's underlying assumptions]
## Common Violations {/*common-violations*/}
[Description of violation patterns]
### Invalid {/*invalid*/}
Examples of incorrect code for this rule:
```js
// X Missing dependency
useEffect(() => {
console.log(count);
}, []); // Missing 'count'
Valid {/valid/}
Examples of correct code for this rule:
// checkmark All dependencies includeduseEffect(() => {
console.log(count);
}, [count]);
Troubleshooting {/troubleshooting/}
[Problem description] {/problem-slug/}
[Solution]
Options {/options/}
[Configuration options if applicable]
**Key characteristics:**
- Intro is a single "Validates that..." sentence
- Uses "Invalid"/"Valid" sections with emoji-prefixed code comments
- Rule Details explains "why" not just "what"
---
### Type F: Index/Category
**When to use:** Overview pages listing multiple APIs in a category
```mdx
---
title: "Built-in React [Type]"
---
<Intro>
*Concept* let you [purpose]. Brief scope statement.
</Intro>
---
## Category Name {/*category-name*/}
*Concept* explanation with [Learn section link](/learn/topic).
To [action], use one of these [Type]:
* [`apiName`](/reference/react/apiName) lets you [action].
* [`apiName`](/reference/react/apiName) declares [thing].
```js
function Example() {
const value = useHookName(args);
}
**Key characteristics:**
- Title format: "Built-in React [Type]"
- Italicized concept definitions
- Horizontal rules between sections
- Closes with "Your own [Type]" section
---
## Advanced Patterns
### Multi-Function Documentation
**When to use:** When a hook returns a function that needs its own documentation (useState's setter, useReducer's dispatch)
```md
### `hookName(args)` {/*hookname*/}
[Main hook documentation]
#### Parameters {/*parameters*/}
#### Returns {/*returns*/}
#### Caveats {/*caveats*/}
---
### `set` functions, like `setSomething(nextState)` {/*setstate*/}
The `set` function returned by `hookName` lets you [action].
#### Parameters {/*setstate-parameters*/}
#### Returns {/*setstate-returns*/}
#### Caveats {/*setstate-caveats*/}
Key conventions:
Horizontal rule (---) separates main hook from returned function
Heading IDs include prefix: {/*setstate-parameters*/} vs {/*parameters*/}
Use generic names: "set functions" not "setCount"
Compound Return Objects
When to use: When a function returns an object with multiple properties/methods (createContext)
### `createContext(defaultValue)` {/*createcontext*/}
[Main function documentation]
#### Returns {/*returns*/}`createContext` returns a context object.
**The context object itself does not hold any information.** It represents...
*`SomeContext` lets you provide the context value.
*`SomeContext.Consumer` is an alternative way to read context.
---
### `SomeContext` Provider {/*provider*/}
[Documentation for Provider]
#### Props {/*provider-props*/}
---
### `SomeContext.Consumer` {/*consumer*/}
[Documentation for Consumer]
#### Props {/*consumer-props*/}
Writing Patterns
Opening Lines by Page Type
Page Type
Pattern
Example
Hook
`hookName` is a React Hook that lets you [action].
"useState is a React Hook that lets you add a state variable to your component."
Component
`<ComponentName>` lets you [action].
"<Suspense> lets you display a fallback until its children have finished loading."
API
`apiName` lets you [action].
"memo lets you skip re-rendering a component when its props are unchanged."
Configuration
The `optionName` option [controls/specifies/determines] [what].
"The target option specifies which React version the compiler generates code for."
Directive
`'directive'` [marks/opts/prevents] [what] for [purpose].
"'use server' marks a function as callable from the client."
ESLint Rule
Validates that [condition].
"Validates that dependency arrays for React hooks contain all necessary dependencies."
Parameter Patterns
Simple parameter:
*`paramName`: Description of what it does.
Optional parameter:
***optional**`paramName`: Description of what it does.
Parameter with special function behavior:
*`initialState`: The value you want the state to be initially. It can be a value of any type, but there is a special behavior for functions. This argument is ignored after the initial render.
* If you pass a function as `initialState`, it will be treated as an _initializer function_. It should be pure, should take no arguments, and should return a value of any type.
Callback parameter with sub-parameters:
*`subscribe`: A function that takes a single `callback` argument and subscribes it to the store. When the store changes, it should invoke the provided `callback`. The `subscribe` function should return a function that cleans up the subscription.
Nested options object:
***optional**`options`: An object with options for this React root.
***optional**`onCaughtError`: Callback called when React catches an error in an Error Boundary.
***optional**`onUncaughtError`: Callback called when an error is thrown and not caught.
***optional**`identifierPrefix`: A string prefix React uses for IDs generated by `useId`.
Return Value Patterns
Single value return:
`hookName` returns the current value. The value will be the same as `initialValue` during the first render.
Array return (numbered list):
`useState` returns an array with exactly two values:
1. The current state. During the first render, it will match the `initialState` you have passed.
2. The [`set` function](#setstate) that lets you update the state to a different value and trigger a re-render.
Object return (bulleted list):
`createElement` returns a React element object with a few properties:
*`type`: The `type` you have passed.
*`props`: The `props` you have passed except for `ref` and `key`.
*`ref`: The `ref` you have passed. If missing, `null`.
*`key`: The `key` you have passed, coerced to a string. If missing, `null`.
Promise return:
`prerender` returns a Promise:
- If rendering is successful, the Promise will resolve to an object containing:
-`prelude`: a [Web Stream](MDN-link) of HTML.
-`postponed`: a JSON-serializable object for resumption.
- If rendering fails, the Promise will be rejected.
Wrapped function return:
`cache` returns a cached version of `fn` with the same type signature. It does not call `fn` in the process.
When calling `cachedFn` with given arguments, it first checks if a cached result exists. If cached, it returns the result. If not, it calls `fn`, stores the result, and returns it.
Caveats Patterns
Standard Hook caveat (almost always first for Hooks):
*`useXxx` is a Hook, so you can only call it **at the top level of your component** or your own Hooks. You can't call it inside loops or conditions. If you need that, extract a new component and move the state into it.
Stable identity caveat (for returned functions):
* The `set` function has a stable identity, so you will often see it omitted from Effect dependencies, but including it will not cause the Effect to fire.
Strict Mode caveat:
* In Strict Mode, React will **call your render function twice** in order to help you find accidental impurities. This is development-only behavior and does not affect production.
Caveat with code example:
* It's not recommended to _suspend_ a render based on a store value returned by `useSyncExternalStore`. For example, the following is discouraged:
```js
const selectedProductId = useSyncExternalStore(...);
const data = use(fetchItem(selectedProductId)) // X Don't suspend based on store value
**Canary caveat:**
```md
* <CanaryBadge /> If you want to pass `ref` to a Fragment, you can't use the `<>...</>` syntax.
Troubleshooting Patterns
Heading format (first person problem statements):
### I've updated the state, but logging gives me the old value {/*old-value*/}### My initializer or updater function runs twice {/*runs-twice*/}### I want to read the latest state from a callback {/*read-latest-state*/}
Error message format:
### I'm getting an error: "Too many re-renders" {/*too-many-rerenders*/}### I'm getting an error: "Rendered more hooks than during the previous render" {/*more-hooks*/}
Lint error format:
### I'm getting a lint error: "[exact error message]" {/*lint-error-slug*/}
`<input>` supports all [common element props.](/reference/react-dom/components/common#common-props)
Props categorization:
Controlled vs uncontrolled props grouped separately
Form-specific props documented with action patterns
MDN links for standard HTML attributes
Environment-specific notes:
<Note>
This API is specific to Node.js. Environments with [Web Streams](MDN-link), like Deno and modern edge runtimes, should use [`renderToReadableStream`](/reference/react-dom/server/renderToReadableStream) instead.
</Note>
Progressive enhancement:
Document benefits for users without JavaScript
Explain Server Function + form action integration
Show hidden form field and .bind() patterns
RSC
RSC banner (before Intro):
Always place <RSC> component before <Intro> for Server Component-only APIs.
Serialization type lists:
When documenting Server Function arguments, list supported types:
Supported types for Server Function arguments:
* Primitives
* [string](MDN-link)
* [number](MDN-link)
* Iterables containing serializable values
* [Array](MDN-link)
* [Map](MDN-link)
Notably, these are not supported:
* React elements, or [JSX](/learn/writing-markup-with-jsx)
* Functions (other than Server Functions)
Bundle size comparisons:
Show "Not included in bundle" for server-only imports
Annotate client bundle sizes with gzip: // 35.9K (11.2K gzipped)
Compiler
Configuration page structure:
Type (union type or interface)
Default value
Options/Valid values with descriptions
Directive documentation:
Placement requirements are critical
Mode interaction tables showing combinations
"Use sparingly" + "Plan for removal" patterns for escape hatches
Library author guides:
Audience-first intro
Benefits/Why section
Numbered step-by-step setup
ESLint
Rule Details section:
Explain "why" not just "what"
Focus on React's underlying assumptions
Describe consequences of violations
Invalid/Valid sections:
Standard intro: "Examples of [in]correct code for this rule:"
Use X emoji for invalid, checkmark for valid
Show inline comments explaining the violation
Configuration options:
Show shared settings (preferred)
Show rule-level options (backward compatibility)
Note precedence when both exist
Edge Cases
For deprecated, canary, and version-specific component patterns (placement, syntax, examples), invoke /docs-components.
Quick placement rules:
<Deprecated> after <Intro> for page-level, after heading for method-level
<Canary> wrapper inline in Intro, <CanaryBadge /> in headings/props/caveats
Version notes use <Note> with "Starting in React 19..." pattern
Removed APIs on index pages:
## Removed APIs {/*removed-apis*/}
These APIs were removed in React 19:
* [`render`](https://18.react.dev/reference/react-dom/render): use [`createRoot`](/reference/react-dom/client/createRoot) instead.
Link to previous version docs (18.react.dev) for removed API documentation.
Critical Rules
Heading IDs required:## Title {/*title-id*/} (lowercase, hyphens)
Sandpack main file needs export default
Active file syntax:```js src/File.js active
Error headings in Troubleshooting: Use ### I'm getting an error: "[message]" {/*id*/}
Section dividers (---) required between headings (see Section Dividers below)
InlineToc required: Always include <InlineToc /> after Intro
Consistent parameter format: Use * \paramName`: descriptionwithoptional` prefix for optional params
Numbered lists for array returns: When hooks return arrays, use numbered lists in Returns section
Generic names for returned functions: Use "set functions" not "setCount"
Props vs Parameters: Use #### Props for Components (Type B), #### Parameters for Hooks/APIs (Type A)
RSC placement:<RSC> component goes before <Intro>, not after
Canary markers: Use <Canary> wrapper inline in Intro, <CanaryBadge /> in headings/props
Deprecated placement:<Deprecated> goes after <Intro> for page-level, after heading for method-level
Code comment emojis: Use X for wrong, checkmark for correct in code examples
No consecutive Pitfalls/Notes: Combine into one component with titled subsections, or separate with prose/code (see /docs-components)
For component heading level conventions (DeepDive, Pitfall, Note, Recipe headings), see /docs-components.
Section Dividers
Use --- horizontal rules to visually separate major sections:
After <InlineToc /> - Before ## Reference heading
Between API subsections - Between different function/hook definitions (e.g., between useState() and set functions)
Before ## Usage - Separates API reference from examples
Before ## Troubleshooting - Separates content from troubleshooting
Between EVERY Usage subsections - When switching to a new major use case
