/docs-components

name: docs-components
description: Comprehensive MDX component patterns (Note, Pitfall, DeepDive, Recipes, etc.) for all documentation types. Authoritative source for component usage, examples, and heading conventions.

MDX Component Patterns

Quick Reference

Component Decision Tree

| Need | Component | |------|-----------| | Helpful tip or terminology | `<Note>` | | Common mistake warning | `<Pitfall>` | | Advanced technical explanation | `<DeepDive>` | | Canary-only feature | `<Canary>` or `<CanaryBadge />` | | Server Components only | `<RSC>` | | Deprecated API | `<Deprecated>` | | Experimental/WIP | `<Wip>` | | Visual diagram | `<Diagram>` | | Multiple related examples | `<Recipes>` | | Interactive code | `<Sandpack>` (see `/docs-sandpack`) | | Console error display | `<ConsoleBlock>` | | End-of-page exercises | `<Challenges>` (Learn pages only) |

Heading Level Conventions

| Component | Heading Level | |-----------|---------------| | DeepDive title | `####` (h4) | | Titled Pitfall | `#####` (h5) | | Titled Note | `####` (h4) | | Recipe items | `####` (h4) | | Challenge items | `####` (h4) |

Callout Spacing Rules

Callout components (Note, Pitfall, DeepDive) require a **blank line after the opening tag** before content begins.

**Never place consecutively:**

• `<Pitfall>` followed by `<Pitfall>` - Combine into one with titled subsections, or separate with prose
• `<Note>` followed by `<Note>` - Combine into one, or separate with prose

**Allowed consecutive patterns:**

• `<DeepDive>` followed by `<DeepDive>` - OK for multi-part explorations (see useMemo.md)
• `<Pitfall>` followed by `<DeepDive>` - OK when DeepDive explains "why" behind the Pitfall

**Separation content:** Prose paragraphs, code examples (Sandpack), or section headers.

**Why:** Consecutive warnings create a "wall of cautions" that overwhelms readers and causes important warnings to be skimmed.

**Incorrect:**

<Pitfall>
Don't do X.
</Pitfall>

<Pitfall>
Don't do Y.
</Pitfall>

**Correct - combined:**

<Pitfall>

##### Don't do X {/*pitfall-x*/}
Explanation.

##### Don't do Y {/*pitfall-y*/}
Explanation.

</Pitfall>

**Correct - separated:**

<Pitfall>
Don't do X.
</Pitfall>

This leads to another common mistake:

<Pitfall>
Don't do Y.
</Pitfall>

---

`<Note>`

Important clarifications, conventions, or tips. Less severe than Pitfall.

Simple Note

<Note>

The optimization of caching return values is known as [_memoization_](https://en.wikipedia.org/wiki/Memoization).

</Note>

Note with Title

Use `####` (h4) heading with an ID.

<Note>

#### There is no directive for Server Components. {/*no-directive*/}

A common misunderstanding is that Server Components are denoted by `"use server"`, but there is no directive for Server Components. The `"use server"` directive is for Server Functions.

</Note>

Version-Specific Note

<Note>

Starting in React 19, you can render `<SomeContext>` as a provider.

In older versions of React, use `<SomeContext.Provider>`.

</Note>

---

`<Pitfall>`

Common mistakes that cause bugs. Use for errors readers will likely make.

Simple Pitfall

<Pitfall>

We recommend defining components as functions instead of classes. [See how to migrate.](#alternatives)

</Pitfall>

Titled Pitfall

Use `#####` (h5) heading with an ID.

<Pitfall>

##### Calling different memoized functions will read from different caches. {/*pitfall-different-caches*/}

To access the same cache, components must call the same memoized function.

</Pitfall>

Pitfall with Wrong/Right Code

<Pitfall>

##### `useFormStatus` will not return status information for a `<form>` rendered in the same component. {/*pitfall-same-component*/}

```js
function Form() {
  // 🔴 `pending` will never be true
  const { pending } = useFormStatus();
  return <form action={submit}></form>;
}

Instead call `useFormStatus` from inside a component located inside `<form>`.

</Pitfall>

---

## `<DeepDive>`

Optional deep technical content. **First child must be `####` heading with ID.**

### Standard DeepDive

```mdx
<DeepDive>

#### Is using an updater always preferred? {/*is-updater-preferred*/}

You might hear a recommendation to always write code like `setAge(a => a + 1)` if the state you're setting is calculated from the previous state. There's no harm in it, but it's also not always necessary.

In most cases, there is no difference between these two approaches. React always makes sure that for intentional user actions, like clicks, the `age` state variable would be updated before the next click.

</DeepDive>

Comparison DeepDive

For comparing related concepts:

<DeepDive>

#### When should I use `cache`, `memo`, or `useMemo`? {/*cache-memo-usememo*/}

All mentioned APIs offer memoization but differ in what they memoize, who can access the cache, and when their cache is invalidated.

#### `useMemo` {/*deep-dive-usememo*/}

In general, you should use `useMemo` for caching expensive computations in Client Components across renders.

#### `cache` {/*deep-dive-cache*/}

In general, you should use `cache` in Server Components to memoize work that can be shared across components.

</DeepDive>

---

`<Recipes>`

Multiple related examples showing variations. Each recipe needs `<Solution />`.

<Recipes titleText="Basic useState examples" titleId="examples-basic">

#### Counter (number) {/*counter-number*/}

In this example, the `count` state variable holds a number.

<Sandpack>
{/* code */}
</Sandpack>

<Solution />

#### Text field (string) {/*text-field-string*/}

In this example, the `text` state variable holds a string.

<Sandpack>
{/* code */}
</Sandpack>

<Solution />

</Recipes>

**Common titleText/titleId combinations:**

• "Basic [hookName] examples" / `examples-basic`
• "Examples of [concept]" / `examples-[concept]`
• "The difference between [A] and [B]" /