APIリファレンス
コンポーネント

共通コンポーネント (例: <div>)

<div> のような、組み込みのブラウザコンポーネントはすべて、いくつかの共通の props とイベントをサポートしています。

リファレンス

共通コンポーネント (例: <div>) 

<div className="wrapper">Some content</div>

以下の例もご覧ください。

Props

これらの特別なReact propsは、すべての組み込みコンポーネントでサポートされています

  • children: Reactノード（要素、文字列、数値、ポータル、null、undefined、およびブール値のような空のノード、または他のReactノードの配列）。コンポーネント内のコンテンツを指定します。JSXを使用する場合、通常、<div><span /></div>のようにタグをネストすることで、children propsを暗黙的に指定します。

  • dangerouslySetInnerHTML: { __html: '<p>some html</p>' } の形式のオブジェクトで、中に生のHTML文字列が入っています。DOMノードのinnerHTMLプロパティを上書きし、渡されたHTMLを内部に表示します。これは非常に注意して使用する必要があります！内部のHTMLが信頼できない場合（例えば、ユーザーデータに基づく場合）、XSS脆弱性を導入するリスクがあります。dangerouslySetInnerHTMLの使用についてさらに詳しく読んでください。

  • ref: useRefまたはcreateRefからのrefオブジェクト、またはrefコールバック関数、またはレガシーrefs用の文字列。このノードのDOM要素がrefに設定されます。refsを使ったDOMの操作についてさらに詳しく読んでください。

  • suppressContentEditableWarning: ブール値。trueの場合、childrenとcontentEditable={true}の両方を持つ要素に対してReactが表示する警告を抑制します（通常、これらは一緒に機能しません）。contentEditableの内容を手動で管理するテキスト入力ライブラリを構築する場合に使用します。

  • suppressHydrationWarning: ブール値。サーバーレンダリングを使用する場合、通常、サーバーとクライアントが異なるコンテンツをレンダリングすると警告が表示されます。一部のまれなケース（タイムスタンプなど）では、完全に一致させることは非常に困難または不可能です。suppressHydrationWarningをtrueに設定すると、Reactはその要素の属性と内容の不一致について警告しません。これは1レベルの深さでのみ機能し、エスケープハッチとして使用することを目的としています。過度に使用しないでください。ハイドレーションエラーの抑制について読んでください。

  • style: CSSスタイルを持つオブジェクト。例えば、{ fontWeight: 'bold', margin: 20 } のような形式です。DOMのstyleプロパティと同様に、CSSプロパティ名はcamelCaseで記述する必要があります。例えば、font-weightの代わりにfontWeightとします。値として文字列または数値を渡すことができます。数値（例えば、width: 100）を渡すと、Reactはそれが単位のないプロパティでない限り、値に自動的にpx（「ピクセル」）を追加します。styleは、スタイルの値を事前に知らない動的なスタイルにのみ使用することをお勧めします。それ以外の場合は、classNameでプレーンなCSSクラスを適用する方が効率的です。classNameとstyleの適用についてさらに詳しく読んでください。

これらの標準的なDOMプロパティは、すべての組み込みコンポーネントでもサポートされています。

カスタム属性をpropsとして渡すこともできます。例：mycustomprop="someValue"。これは、サードパーティのライブラリと統合する場合に役立ちます。カスタム属性の名前は小文字で、on で始まることはできません。値は文字列に変換されます。null または undefined を渡すと、カスタム属性は削除されます。

これらのイベントは、<form> 要素に対してのみ発生します。

これらのイベントは、<dialog> 要素に対してのみ発生します。ブラウザのイベントとは異なり、React ではバブリングします。

これらのイベントは、<details> 要素に対してのみ発生します。ブラウザのイベントとは異なり、React ではバブリングします。

これらのイベントは、<img>、<iframe>、<object>、<embed>、<link>、および SVG <image> 要素に対して発生します。ブラウザのイベントとは異なり、React ではバブリングします。

  • onLoad: Event ハンドラー関数。リソースのロードが完了したときに発生します。
  • onLoadCapture: onLoad のキャプチャフェーズで発生するバージョンです。キャプチャフェーズを参照してください。
  • onError: Event ハンドラー関数。リソースをロードできなかったときに発生します。
  • onErrorCapture: onError のキャプチャフェーズで発生するバージョンです。キャプチャフェーズを参照してください。

これらのイベントは、<audio> や <video> のようなリソースに対して発生します。ブラウザのイベントとは異なり、React ではバブリングします。

注意事項

  • children と dangerouslySetInnerHTML を同時に渡すことはできません。
  • 一部のイベント (onAbort や onLoad など) はブラウザではバブリングしませんが、React ではバブリングします。

ref コールバック関数

ref オブジェクト (例えば、useRef によって返されるもの) の代わりに、関数を ref 属性に渡すことができます。

<div ref={(node) => {
  console.log('Attached', node);

  return () => {
    console.log('Clean up', node)
  }
}}>

ref コールバックの使用例をご覧ください。

<div> DOM ノードが画面に追加されると、React は DOM node を引数として ref コールバックを呼び出します。その <div> DOM ノードが削除されると、React はコールバックから返されたクリーンアップ関数を呼び出します。

React は、異なる ref コールバックを渡すたびに、ref コールバックも呼び出します。上記の例では、(node) => { ... } はレンダリングごとに異なる関数です。コンポーネントが再レンダリングされると、以前の 関数は引数として null を渡して呼び出され、次の 関数は DOM ノードを渡して呼び出されます。

パラメーター

  • node: DOM ノード。React は ref がアタッチされると DOM ノードを渡します。レンダリングごとに ref コールバックに同じ関数参照を渡さない限り、コールバックはコンポーネントの再レンダリングごとに一時的にクリーンアップされ、再作成されます。

補足

React 19 では、ref コールバックのクリーンアップ関数が追加されました。

後方互換性をサポートするために、ref コールバックからクリーンアップ関数が返されない場合、ref がデタッチされると、node は null を渡して呼び出されます。この動作は将来のバージョンで削除されます。

戻り値

  • 任意 クリーンアップ関数: ref がデタッチされると、React はクリーンアップ関数を呼び出します。ref コールバックによって関数が返されない場合、React は ref がデタッチされるときに、引数として null を渡してコールバックを再度呼び出します。この動作は将来のバージョンで削除されます。

注意事項

  • 厳格モードがオンの場合、React は最初の実際のセットアップの前に、開発専用の追加のセットアップとクリーンアップのサイクルを 1 回実行します。これは、クリーンアップロジックがセットアップロジックを「ミラーリング」し、セットアップが行っていることを停止または取り消すことを保証するストレステストです。これにより問題が発生する場合は、クリーンアップ関数を実装してください。
  • 異なる ref コールバックを渡すと、React は提供されている場合は以前のコールバックのクリーンアップ関数を呼び出します。クリーンアップ関数が定義されていない場合、ref コールバックは引数として null を渡して呼び出されます。次の関数は DOM ノードを渡して呼び出されます。

Reactイベントオブジェクト

イベントハンドラーはReactイベントオブジェクトを受け取ります。これは「合成イベント」とも呼ばれます。

<button onClick={e => {
  console.log(e); // React event object
}} />

これは、基盤となるDOMイベントと同じ標準に準拠していますが、一部のブラウザの非互換性を修正します。

一部のReactイベントは、ブラウザのネイティブイベントに直接マッピングされません。たとえば、onMouseLeaveでは、e.nativeEventはmouseoutイベントを指します。特定のマッピングはパブリックAPIの一部ではなく、将来変更される可能性があります。何らかの理由で基盤となるブラウザイベントが必要な場合は、e.nativeEventから読み取ってください。

プロパティ

Reactイベントオブジェクトは、標準のEventプロパティの一部を実装します。

  • bubbles: ブール値。イベントがDOMをバブリングするかどうかを返します。
  • cancelable: ブール値。イベントをキャンセルできるかどうかを返します。
  • currentTarget: DOMノード。Reactツリーで現在のハンドラーがアタッチされているノードを返します。
  • defaultPrevented: ブール値。preventDefaultが呼び出されたかどうかを返します。
  • eventPhase: 数値。イベントが現在どのフェーズにあるかを返します。
  • isTrusted: ブール値。イベントがユーザーによって開始されたかどうかを返します。
  • target: DOMノード。イベントが発生したノード（遠い子ノードである可能性もあります）を返します。
  • timeStamp: 数値。イベントが発生した時刻を返します。

さらに、Reactイベントオブジェクトは次のプロパティを提供します

  • nativeEvent: DOM Event。元のブラウザイベントオブジェクト。

メソッド

Reactイベントオブジェクトは、標準のEventメソッドの一部を実装します。

  • preventDefault(): イベントのブラウザのデフォルトアクションを防止します。
  • stopPropagation(): Reactツリーを介したイベントの伝播を停止します。

さらに、Reactイベントオブジェクトは次のメソッドを提供します

  • isDefaultPrevented(): preventDefaultが呼び出されたかどうかを示すブール値を返します。
  • isPropagationStopped(): stopPropagationが呼び出されたかどうかを示すブール値を返します。
  • persist(): React DOMでは使用されません。React Nativeでは、イベント後にイベントのプロパティを読み取るためにこれを呼び出します。
  • isPersistent(): React DOMでは使用されません。React Nativeでは、persistが呼び出されたかどうかを返します。

注意点

  • currentTarget、eventPhase、target、およびtypeの値は、Reactコードが期待する値を反映しています。内部的には、Reactはルートにイベントハンドラーをアタッチしますが、これはReactイベントオブジェクトには反映されません。たとえば、e.currentTargetは、基盤となるe.nativeEvent.currentTargetと同じではない可能性があります。ポリフィルされたイベントの場合、e.type（Reactイベントタイプ）は、e.nativeEvent.type（基盤となるタイプ）と異なる場合があります。

AnimationEvent ハンドラー関数

CSS アニメーションイベントのイベントハンドラーの型です。

<div
  onAnimationStart={e => console.log('onAnimationStart')}
  onAnimationIteration={e => console.log('onAnimationIteration')}
  onAnimationEnd={e => console.log('onAnimationEnd')}
/>

パラメーター

ClipboardEvent ハンドラー関数

クリップボード API イベントのイベントハンドラーの型です。

<input
  onCopy={e => console.log('onCopy')}
  onCut={e => console.log('onCut')}
  onPaste={e => console.log('onPaste')}
/>

パラメーター

CompositionEvent ハンドラー関数

インプットメソッドエディター (IME) イベントのイベントハンドラーの型です。

<input
  onCompositionStart={e => console.log('onCompositionStart')}
  onCompositionUpdate={e => console.log('onCompositionUpdate')}
  onCompositionEnd={e => console.log('onCompositionEnd')}
/>

パラメーター

DragEvent ハンドラー関数

HTML ドラッグアンドドロップ API イベントのイベントハンドラーの型です。

<>
  <div
    draggable={true}
    onDragStart={e => console.log('onDragStart')}
    onDragEnd={e => console.log('onDragEnd')}
  >
    Drag source
  </div>

  <div
    onDragEnter={e => console.log('onDragEnter')}
    onDragLeave={e => console.log('onDragLeave')}
    onDragOver={e => { e.preventDefault(); console.log('onDragOver'); }}
    onDrop={e => console.log('onDrop')}
  >
    Drop target
  </div>
</>

パラメーター

FocusEvent ハンドラー関数

フォーカスイベントのイベントハンドラーの型。

<input
  onFocus={e => console.log('onFocus')}
  onBlur={e => console.log('onBlur')}
/>

例を参照してください。

パラメーター

Event ハンドラー関数

汎用イベントのイベントハンドラーの型。

パラメーター

InputEvent ハンドラー関数

onBeforeInput イベントのイベントハンドラーの型。

<input onBeforeInput={e => console.log('onBeforeInput')} />

パラメーター

KeyboardEvent ハンドラー関数

キーボードイベントのイベントハンドラーの型。

<input
  onKeyDown={e => console.log('onKeyDown')}
  onKeyUp={e => console.log('onKeyUp')}
/>

例を参照してください。

パラメーター

MouseEvent ハンドラー関数

マウスイベントのイベントハンドラーの型。

<div
  onClick={e => console.log('onClick')}
  onMouseEnter={e => console.log('onMouseEnter')}
  onMouseOver={e => console.log('onMouseOver')}
  onMouseDown={e => console.log('onMouseDown')}
  onMouseUp={e => console.log('onMouseUp')}
  onMouseLeave={e => console.log('onMouseLeave')}
/>

例を参照してください。

パラメータ

PointerEvent ハンドラー関数

ポインターイベントのイベントハンドラーの型。

<div
  onPointerEnter={e => console.log('onPointerEnter')}
  onPointerMove={e => console.log('onPointerMove')}
  onPointerDown={e => console.log('onPointerDown')}
  onPointerUp={e => console.log('onPointerUp')}
  onPointerLeave={e => console.log('onPointerLeave')}
/>

例を参照してください。

パラメータ

TouchEvent ハンドラー関数

タッチイベントのイベントハンドラーの型。

<div
  onTouchStart={e => console.log('onTouchStart')}
  onTouchMove={e => console.log('onTouchMove')}
  onTouchEnd={e => console.log('onTouchEnd')}
  onTouchCancel={e => console.log('onTouchCancel')}
/>

パラメータ

TransitionEvent ハンドラー関数

CSS transition イベントのイベントハンドラーの型。

<div
  onTransitionEnd={e => console.log('onTransitionEnd')}
/>

パラメータ

UIEvent ハンドラー関数

汎用的なUIイベントのイベントハンドラーの型。

<div
  onScroll={e => console.log('onScroll')}
/>

パラメータ

WheelEvent ハンドラー関数

onWheel イベントのイベントハンドラーの型です。

<div
  onWheel={e => console.log('onWheel')}
/>

パラメーター

使用法

CSSスタイルの適用

Reactでは、classNameでCSSクラスを指定します。 これは、HTMLのclass属性と同様に機能します。

<img className="avatar" />

次に、別のCSSファイルにそのCSSルールを記述します。

/* In your CSS */
.avatar {
  border-radius: 50%;
}

Reactは、CSSファイルの追加方法を指定していません。最も簡単な場合は、HTMLに<link>タグを追加します。ビルドツールまたはフレームワークを使用する場合は、そのドキュメントを参照して、プロジェクトにCSSファイルを追加する方法を確認してください。

場合によっては、スタイル値がデータに依存することがあります。style属性を使用して、いくつかのスタイルを動的に渡します。

<img
  className="avatar"
  style={{
    width: user.imageSize,
    height: user.imageSize
  }}
/>

上記の例では、style={{}}は特別な構文ではなく、style={ } JSXの中括弧の中にある通常の{}オブジェクトです。スタイルがJavaScript変数に依存する場合にのみ、style属性を使用することをお勧めします。

export default function Avatar({ user }) {
  return (
    <img
      src={user.imageUrl}
      alt={'Photo of ' + user.name}
      className="avatar"
      style={{
        width: user.imageSize,
        height: user.imageSize
      }}
    />
  );
}
詳細

複数のCSSクラスを条件付きで適用する方法は？

CSSクラスを条件付きで適用するには、JavaScriptを使用してclassName文字列を自分で生成する必要があります。

たとえば、className={'row ' + (isSelected ? 'selected': '')}は、isSelectedがtrueであるかどうかによって、className="row"またはclassName="row selected"を生成します。

これをより読みやすくするために、classnamesのような小さなヘルパーライブラリを使用できます。

import cn from 'classnames';

function Row({ isSelected }) {
  return (
    <div className={cn('row', isSelected && 'selected')}>
      ...
    </div>
  );
}

複数の条件付きクラスがある場合に特に便利です

import cn from 'classnames';

function Row({ isSelected, size }) {
  return (
    <div className={cn('row', {
      selected: isSelected,
      large: size === 'large',
      small: size === 'small',
    })}>
      ...
    </div>
  );
}

refを使用したDOMノードの操作

JSX内のタグに関連付けられたブラウザのDOMノードを取得する必要がある場合があります。例えば、ボタンがクリックされたときに<input>にフォーカスを当てたい場合、ブラウザの<input> DOMノードでfocus()を呼び出す必要があります。

タグのブラウザDOMノードを取得するには、refを宣言し、そのタグにref属性として渡します。

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);
  // ...
  return (
    <input ref={inputRef} />
    // ...

Reactは、画面にレンダリングされた後、DOMノードをinputRef.currentに格納します。

import { useRef } from 'react';

export default function Form() {
  const inputRef = useRef(null);

  function handleClick() {
    inputRef.current.focus();
  }

  return (
    <>
      <input ref={inputRef} />
      <button onClick={handleClick}>
        Focus the input
      </button>
    </>
  );
}

refsを使ったDOMの操作とその他の例についてもっと読む。

より高度なユースケースでは、ref属性はコールバック関数も受け入れます。

危険なinnerHTMLの設定

次のように、生のHTML文字列を要素に渡すことができます。

const markup = { __html: '<p>some raw html</p>' };
return <div dangerouslySetInnerHTML={markup} />;

これは危険です。基礎となるDOMのinnerHTMLプロパティと同様に、細心の注意を払う必要があります！マークアップが完全に信頼できるソースから提供されていない限り、このようにXSSの脆弱性を導入するのは簡単です。

たとえば、MarkdownをHTMLに変換するMarkdownライブラリを使用する場合、そのパーサーにバグが含まれておらず、ユーザーが自分の入力のみを表示することを確認すれば、次のように結果のHTMLを表示できます。

import { Remarkable } from 'remarkable';

const md = new Remarkable();

function renderMarkdownToHTML(markdown) {
  // This is ONLY safe because the output HTML
  // is shown to the same user, and because you
  // trust this Markdown parser to not have bugs.
  const renderedHTML = md.render(markdown);
  return {__html: renderedHTML};
}

export default function MarkdownPreview({ markdown }) {
  const markup = renderMarkdownToHTML(markdown);
  return <div dangerouslySetInnerHTML={markup} />;
}

{__html}オブジェクトは、上記の例でrenderMarkdownToHTML関数が行っているように、HTMLが生成される場所にできるだけ近い場所に作成する必要があります。これにより、コードで使用されているすべての生のHTMLが明示的にマークされ、HTMLが含まれることが予想される変数のみがdangerouslySetInnerHTMLに渡されるようになります。 <div dangerouslySetInnerHTML={{__html: markup}} />のようにインラインでオブジェクトを作成することは推奨されません。

任意のHTMLをレンダリングするのが危険な理由を確認するには、上記のコードを次のコードに置き換えてください。

const post = {
  // Imagine this content is stored in the database.
  content: `<img src="" onerror='alert("you were hacked")'>`
};

export default function MarkdownPreview() {
  // 🔴 SECURITY HOLE: passing untrusted input to dangerouslySetInnerHTML
  const markup = { __html: post.content };
  return <div dangerouslySetInnerHTML={markup} />;
}

HTMLに埋め込まれたコードが実行されます。ハッカーは、このセキュリティホールを利用して、ユーザー情報を盗んだり、ユーザーの代わりにアクションを実行したりする可能性があります。信頼できるサニタイズされたデータでのみdangerouslySetInnerHTMLを使用してください。

マウスイベントの処理

この例は、いくつかの一般的なマウスイベントとそれらがいつ発生するかを示しています。

export default function MouseExample() {
  return (
    <div
      onMouseEnter={e => console.log('onMouseEnter (parent)')}
      onMouseLeave={e => console.log('onMouseLeave (parent)')}
    >
      <button
        onClick={e => console.log('onClick (first button)')}
        onMouseDown={e => console.log('onMouseDown (first button)')}
        onMouseEnter={e => console.log('onMouseEnter (first button)')}
        onMouseLeave={e => console.log('onMouseLeave (first button)')}
        onMouseOver={e => console.log('onMouseOver (first button)')}
        onMouseUp={e => console.log('onMouseUp (first button)')}
      >
        First button
      </button>
      <button
        onClick={e => console.log('onClick (second button)')}
        onMouseDown={e => console.log('onMouseDown (second button)')}
        onMouseEnter={e => console.log('onMouseEnter (second button)')}
        onMouseLeave={e => console.log('onMouseLeave (second button)')}
        onMouseOver={e => console.log('onMouseOver (second button)')}
        onMouseUp={e => console.log('onMouseUp (second button)')}
      >
        Second button
      </button>
    </div>
  );
}

ポインターイベントの処理

この例は、いくつかの一般的なポインターイベントとそれらがいつ発生するかを示しています。

export default function PointerExample() {
  return (
    <div
      onPointerEnter={e => console.log('onPointerEnter (parent)')}
      onPointerLeave={e => console.log('onPointerLeave (parent)')}
      style={{ padding: 20, backgroundColor: '#ddd' }}
    >
      <div
        onPointerDown={e => console.log('onPointerDown (first child)')}
        onPointerEnter={e => console.log('onPointerEnter (first child)')}
        onPointerLeave={e => console.log('onPointerLeave (first child)')}
        onPointerMove={e => console.log('onPointerMove (first child)')}
        onPointerUp={e => console.log('onPointerUp (first child)')}
        style={{ padding: 20, backgroundColor: 'lightyellow' }}
      >
        First child
      </div>
      <div
        onPointerDown={e => console.log('onPointerDown (second child)')}
        onPointerEnter={e => console.log('onPointerEnter (second child)')}
        onPointerLeave={e => console.log('onPointerLeave (second child)')}
        onPointerMove={e => console.log('onPointerMove (second child)')}
        onPointerUp={e => console.log('onPointerUp (second child)')}
        style={{ padding: 20, backgroundColor: 'lightblue' }}
      >
        Second child
      </div>
    </div>
  );
}

フォーカスイベントの処理

Reactでは、フォーカスイベントはバブルします。currentTargetとrelatedTargetを使用すると、フォーカスまたはブラーイベントが親要素の外から発生したかどうかを区別できます。この例では、子にフォーカスを当てる方法、親要素にフォーカスを当てる方法、サブツリー全体を出入りするフォーカスを検出する方法を示します。

export default function FocusExample() {
  return (
    <div
      tabIndex={1}
      onFocus={(e) => {
        if (e.currentTarget === e.target) {
          console.log('focused parent');
        } else {
          console.log('focused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('focus entered parent');
        }
      }}
      onBlur={(e) => {
        if (e.currentTarget === e.target) {
          console.log('unfocused parent');
        } else {
          console.log('unfocused child', e.target.name);
        }
        if (!e.currentTarget.contains(e.relatedTarget)) {
          // Not triggered when swapping focus between children
          console.log('focus left parent');
        }
      }}
    >
      <label>
        First name:
        <input name="firstName" />
      </label>
      <label>
        Last name:
        <input name="lastName" />
      </label>
    </div>
  );
}

キーボードイベントの処理

この例は、いくつかの一般的なキーボードイベントとそれらがいつ発生するかを示しています。

export default function KeyboardExample() {
  return (
    <label>
      First name:
      <input
        name="firstName"
        onKeyDown={e => console.log('onKeyDown:', e.key, e.code)}
        onKeyUp={e => console.log('onKeyUp:', e.key, e.code)}
      />
    </label>
  );
}
前コンポーネント
次<form>