docs-components

MDX コンポーネントのパターン

クイックリファレンス

コンポーネントの選択フロー

必要なもの	コンポーネント
役立つヒントや用語の説明	<Note>
よくある間違いへの警告	<Pitfall>
高度な技術的説明	<DeepDive>
Canary 版のみの機能	<Canary> または <CanaryBadge />
Server Components のみ	<RSC>
非推奨の API	<Deprecated>
実験的／開発中の機能	<Wip>
視覚的な図	<Diagram>
関連する複数の例	<Recipes>
インタラクティブなコード	<Sandpack>（/docs-sandpack を参照）
コンソールエラーの表示	<ConsoleBlock>
ページ末尾の練習問題	<Challenges>（Learn ページのみ）

見出しレベルの規則

コンポーネント	見出しレベル
DeepDive のタイトル	#### (h4)
タイトル付き Pitfall	##### (h5)
タイトル付き Note	#### (h4)
Recipe の項目	#### (h4)
Challenge の項目	#### (h4)

コールアウトの間隔ルール

コールアウトコンポーネント（Note、Pitfall、DeepDive）では、開始タグの後に空行を入れてからコンテンツを記述してください。

連続して配置しないでください：

• <Pitfall> の後に <Pitfall> を配置する場合：タイトル付きの小見出しを使って1つにまとめるか、説明文を挟みます
• <Note> の後に <Note> を配置する場合：1つにまとめるか、説明文を挟みます

連続して配置できるパターン：

• <DeepDive> の後に <DeepDive> を配置する場合：複数パートに分かれた解説では問題ありません（useMemo.md を参照）
• <Pitfall> の後に <DeepDive> を配置する場合：Pitfall の「理由」を DeepDive で説明する場合は問題ありません

**間に挟むコンテンツ：**説明文の段落、コード例（Sandpack）、セクション見出し。

**理由：**警告を連続させると「注意書きの壁」になり、読者を圧倒して重要な警告が読み飛ばされる原因になります。

誤った例：

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

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

正しい例 - まとめる：

<Pitfall>

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

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

</Pitfall>

正しい例 - 分ける：

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

This leads to another common mistake:

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

---

<Note>

重要な補足、規約、ヒントに使用します。Pitfall より深刻度が低い内容に適しています。

シンプルな Note

<Note>

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

</Note>

タイトル付き Note

ID を指定した #### (h4) 見出しを使用します。

<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>

バージョン固有の Note

<Note>

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

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

</Note>

---

<Pitfall>

バグにつながるよくある間違いに使用します。読者がしそうな間違いに適しています。

シンプルな Pitfall

<Pitfall>

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

</Pitfall>

タイトル付き Pitfall

ID を指定した ##### (h5) 見出しを使用します。

<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

<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>;
}

代わりに、<form> 内に配置されたコンポーネントの中から useFormStatus を呼び出してください。

```

---

<DeepDive>

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

Standard DeepDive

<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>

比較する DeepDive

関連する概念を比較する場合：

<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>

バリエーションを示す、関連する複数の例です。各 recipe には <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>

よく使われる titleText/titleId の組み合わせ：

• "基本的な[hookName]の例" / examples-basic
• "[concept]の例" / examples-[concept]
• "[A]と[B]の違い" / examples-[topic]

---

<Challenges>

ページ末尾の練習問題です。**Learn ページのみ。**各 challenge には問題と解答の Sandpack が必要です。

<Challenges>

#### Fix the bug {/*fix-the-bug*/}

Problem description...

<Hint>
Optional hint text.
</Hint>

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

<Solution>

Explanation...

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

</Solution>

</Challenges>

ガイドライン：

• 標準の Learn ページの末尾にのみ配置します
• 章の導入ページやチュートリアルには Challenges を配置しません
• 各 challenge には ID を指定した #### 見出しを付けます

---

<Deprecated>

非推奨の API に使用します。代わりに何を使うべきかを説明してください。

ページレベルの非推奨表示

<Deprecated>

In React 19, `forwardRef` is no longer necessary. Pass `ref` as a prop instead.

`forwardRef` will be deprecated in a future release. Learn more [here](/blog/2024/04/25/react-19#ref-as-a-prop).

</Deprecated>

メソッドレベルの非推奨表示

### `componentWillMount()` {/*componentwillmount*/}

<Deprecated>

This API has been renamed from `componentWillMount` to [`UNSAFE_componentWillMount`.](#unsafe_componentwillmount)

Run the [`rename-unsafe-lifecycles` codemod](codemod-link) to automatically update.

</Deprecated>

---

<RSC>

React Server Components でのみ動作する API に使用します。

基本的な RSC

<RSC>

`cache` is only for use with [React Server Components](/reference/rsc/server-components).

</RSC>

拡張 RSC（Server Functions 用）

<RSC>

Server Functions are for use in [React Server Components](/reference/rsc/server-components).

**Note:** Until September 2024, we referred to all Server Functions as "Server Actions".

</RSC>

---

<Canary> と <CanaryBadge />

Canary リリースでのみ利用できる機能に使用します。

Canary ラッパー（導入部にインラインで配置）

<Intro>

`<Fragment>` lets you group elements without a wrapper node.

<Canary>Fragments can also accept refs, enabling interaction with underlying DOM nodes.</Canary>

</Intro>

セクション見出しでの CanaryBadge

### <CanaryBadge /> FragmentInstance {/*fragmentinstance*/}

Props リストでの CanaryBadge

* <CanaryBadge /> **optional** `ref`: A ref object from `useRef` or callback function.

注意事項での CanaryBadge

* <CanaryBadge /> If you want to pass `ref` to a Fragment, you can't use the `<>...</>` syntax.

---

<Diagram>

モジュールの依存関係、レンダーツリー、データフローを視覚的に説明します。

<Diagram name="use_client_module_dependency" height={250} width={545} alt="A tree graph with the top node representing the module 'App.js'. 'App.js' has three children...">
`'use client'` segments the module dependency tree, marking `InspirationGenerator.js` and all dependencies as client-rendered.
</Diagram>

属性：

• name：図の識別子（画像ファイルに使用）
• height：高さ（ピクセル単位）
• width：幅（ピクセル単位）
• alt：図のアクセシブルな説明

---

<CodeStep>（使用は控えめに）

説明文中で番号付きコールアウトを使用します。コードブロックの注釈と組み合わせます。

構文

コードブロック内：

```js [[1, 4, "age"], [2, 4, "setAge"], [3, 4, "42"]]
import { useState } from 'react';

function MyComponent() {
  const [age, setAge] = useState(42);
}

Format: `[[step_number, line_number, "text_to_highlight"], ...]`

In prose:
```mdx
1. The <CodeStep step={1}>current state</CodeStep> initially set to the <CodeStep step={3}>initial value</CodeStep>.
2. The <CodeStep step={2}>`set` function</CodeStep> that lets you change it.

ガイドライン

• 説明ごとに異なる色は最大 2～3 色にします
• すべてのキーワードを強調表示せず、重要な概念だけを強調します
• コードブロック全体ではなく、文章内の用語に使用します
• セクション内では一貫して使用します

✅ 適切な例 — 重要な概念を強調：

React will compare the <CodeStep step={2}>dependencies</CodeStep> with the dependencies you passed...

🚫 避ける例 — 過度な強調：

When an <CodeStep step={1}>Activity</CodeStep> boundary is <CodeStep step={2}>hidden</CodeStep> during its <CodeStep step={3}>initial</CodeStep> render...

---

<ConsoleBlock>

コンソール出力（エラー、警告、ログ）を表示します。

<ConsoleBlock level="error">
Uncaught Error: Too many re-renders.
</ConsoleBlock>

レベル： error、warning、info

---

ページの種類ごとのコンポーネントの使い方

リファレンスページ

リファレンスページ固有のコンポーネント配置ルールについては、/docs-writer-reference を呼び出してください。

主な配置パターン：

• <RSC> はページの先頭で <Intro> の前に配置します
• ページ全体に適用される非推奨表示の <Deprecated> は <Intro> の後に配置します
• メソッド単位の非推奨表示の <Deprecated> はメソッドの見出しの後に配置します
• <Canary> ラッパーは <Intro> 内にインラインで配置します
• <CanaryBadge /> は見出し、プロパティの一覧、注意事項に表示します

Learn ページ

Learn ページの構成とパターンについては、/docs-writer-learn を呼び出してください。

主な使用パターン：

• 標準的な Learn ページでは、チャレンジは末尾にのみ配置します
• 章の導入部やチュートリアルにはチャレンジを配置しません
• 任意の高度な内容には DeepDive を使用します
• CodeStep は控えめに使用します

ブログページ

ブログページの構成とパターンについては、/docs-writer-blog を呼び出してください。

主な使用パターン：

• 通常、技術的に詳細なコンポーネントは避けます
• 補足説明には Note と Pitfall を使用できます
• DeepDive よりもインラインでの説明を優先します

---

その他の利用可能なコンポーネント

バージョン／ステータス： <Experimental>、<ExperimentalBadge />、<RSCBadge />、<NextMajor>、<Wip>

ビジュアル： <DiagramGroup>、<Illustration>、<IllustrationBlock>、<CodeDiagram>、<FullWidth>

コンソール： <ConsoleBlockMulti>、<ConsoleLogLine>

特化型： <TerminalBlock>、<BlogCard>、<TeamMember>、<YouTubeIframe>、<ErrorDecoder />、<LearnMore>、<Math>、<MathI>、<LanguageList>

これらのコンポーネントの使用例については、既存のドキュメントを参照してください。