React 19でカスタム要素にpropsとイベントを渡す方法

​​React​CustomEvent,SSR,TypeScript,Web Components

Lit などで作られた UI 部品(Web Components)を React のアプリで使うとき、オブジェクトを渡したり、部品が送るカスタムイベントを受け取ったりしたい場面があります。React 19 では、カスタム要素(<user-card> のようにハイフンを含むタグ)に渡した props は、要素にその名前のプロパティがあればプロパティとして代入されます。イベントは onselect のように on とイベント名をつなげた props で受け取れます。同じコードを React 18 で動かすと、オブジェクトは文字列の属性になり、onselect ではイベントを受け取れませんでした。

ここでは、小さなカスタム要素を作って React 19 から props とイベントを渡し、React 18 と比べた結果をまとめます。

補足

検証環境は Ubuntu 24.04、Node.js 22.23.4 です。React 19.3.1(比較用に React 18.3.1)、TypeScript 7.0.2、esbuild 0.28.2 を使い、tsc で型チェックしてから開発用ビルドで動かしました。ブラウザは Playwright 1.63.0 で開いた Chromium 153(headless)です。Firefox と Safari、Lit などのライブラリで作った要素、Shadow DOM を使う要素、本番用ビルド、ブラウザでのハイドレーションは試していません。サーバーでの描画は renderToString の出力だけを確かめました。

例にするカスタム要素

猫の情報を表示するカード <user-card> を用意しました。表示する猫の情報は、プロパティ user にオブジェクトで渡します。大きさは属性 size で受け取ります。「選ぶ」ボタンを押すと、select という名前の CustomEvent を、detail に猫の情報を入れて送ります。

ts
// user-card.ts
export type User = { name: string; age: number };

export class UserCard extends HTMLElement {
  #user: User | null = null;

  get user() {
    return this.#user;
  }
  set user(value: User | null) {
    this.#user = value;
    this.render();
  }

  static observedAttributes = ['size'];
  attributeChangedCallback() {
    this.render();
  }

  connectedCallback() {
    this.render();
  }

  render() {
    const p = document.createElement('p');
    p.textContent = `${this.#user?.name ?? '(未設定)'}(size=${this.getAttribute('size')})`;
    const button = document.createElement('button');
    button.textContent = '選ぶ';
    button.onclick = () => {
      // 中身を detail に入れて、カスタムイベントを送る
      this.dispatchEvent(new CustomEvent('select', { detail: this.#user, bubbles: true }));
    };
    this.replaceChildren(p, button);
  }
}

要素の登録(customElements.define)は、React が描画を始める前に済ませておきます。理由は後の節で説明します。

tsx
// main.tsx
import { StrictMode } from 'react';
import { createRoot } from 'react-dom/client';
import { App } from './App';
import { UserCard } from './user-card';

customElements.define('user-card', UserCard);

createRoot(document.getElementById('root')!).render(
  <StrictMode>
    <App />
  </StrictMode>,
);

React 19 で props とイベントを渡す

React のコンポーネントからは、ふつうの HTML 要素と同じように JSX に書きます。user にはオブジェクトをそのまま渡し、select イベントは onselect で受け取ります。

tsx
// App.tsx
import { useState } from 'react';
import type { User } from './user-card';

const cats: User[] = [
  { name: 'たま', age: 3 },
  { name: 'みけ', age: 5 },
];

export function App() {
  const [index, setIndex] = useState(0);
  const [selected, setSelected] = useState('');

  return (
    <>
      <user-card
        user={cats[index]}
        size="large"
        onselect={(e) => setSelected(e.detail?.name ?? '')}
      />
      <button onClick={() => setIndex((i) => (i + 1) % cats.length)}>次の猫</button>
      <p>選ばれた猫:{selected}</p>
    </>
  );
}

ブラウザで開くと、カードに「たま(size=large)」と表示されました。「選ぶ」を押すと「選ばれた猫:たま」になり、「次の猫」を押すとカードが「みけ」に変わりました。もう一度「選ぶ」を押すと「選ばれた猫:みけ」です。

枠で囲んだカードに「みけ(size=large)」と「選ぶ」ボタン。その下に「次の猫」ボタンと「選ばれた猫:みけ」。いちばん下の囲みに、user-card の outerHTML として <user-card size="large">…</user-card> と表示されている
「次の猫」を押してから「選ぶ」を押した後の画面。カードの枠と下の囲みは、検証用のページで付けたもの

画面の下に出している要素の HTML を見ると、size は属性になっていますが、user という属性はありません。user はプロパティとして代入されていて、要素の user を読むと { name: 'みけ', age: 5 } というオブジェクトが返りました。

属性になるか、プロパティになるか

React 19 のリリースの記事では、ブラウザでの描画について「カスタム要素のインスタンスにあるプロパティと名前が合う props はプロパティとして代入し、それ以外は属性にする」と説明しています。

これを確かめるため、obj・count・flag の3つのプロパティを持つ要素に、いろいろな props を渡しました。同じコードを React 18 でも動かしています。

渡した props React 19 React 18
obj={{ name: 'たま' }}(プロパティあり) プロパティにオブジェクトのまま入る 属性 obj="[object Object]"
count={3}(プロパティあり) プロパティに数値の 3 が入る 属性 count="3"(文字列)
flag={false}(プロパティあり) プロパティに false が入る 属性 flag="false"
size="large"(プロパティなし) 属性 size="large" 属性 size="large"
flag2={true}(プロパティなし) 属性 flag2="" 属性 flag2="true"
flag3={false}(プロパティなし) 属性を付けない 属性 flag3="false"
className="card" 属性 class="card" 属性 classname="card"

React 18 では、どの値も文字列にした属性になりました。オブジェクトは [object Object] になり、className も class になりません。React 19 では、オブジェクトや数値を型のまま渡せます。props を新しい値にして描き直すと、プロパティも新しい値に変わりました。

要素の登録は、描画より前に済ませる

公式リファレンスにある、カスタム要素に値を渡すときの説明では、要素が作られたときにそのプロパティがあれば、任意の値を渡せるプロパティとして扱うとしています。検証では、customElements.define より先に React が描画すると、オブジェクトは属性 obj="[object Object]" になりました。まだ定義されていない要素には、プロパティ obj がないためです。

その後で define しても、プロパティ obj は undefined のままでした。次に新しいオブジェクトで描き直したときに、初めてプロパティに入りました。最初の描画のときの属性 obj="[object Object]" は、そのまま残っていました。

同じリファレンスの例でも、main.tsx と同じように、customElements.define を済ませてから createRoot で描画しています。部品のライブラリを使うときも、登録が描画より後になると同じことが起きるので、要素を登録するコードの import を、描画より前に置いておきます。

イベントは、名前の大文字・小文字とハイフンをそのまま書く

公式リファレンスにある、カスタム要素のイベントの受け取り方によると、カスタム要素が送るイベントは、on に続けてイベント名を書いた props で受け取れます。イベント名は大文字と小文字を区別し、ハイフンもそのまま書きます。

検証では、1つの要素に onselect・onSelect・oncard-close・onmyEvent・onClick・onselectCapture の6つのハンドラーを渡しました。そこへ5つのイベントを1つずつ送り、そのたびに呼ばれたハンドラーを記録しました。

送ったイベント React 19 で呼ばれたハンドラー
select onselectCapture、onselect(この順)
Select なし
card-close oncard-close
myEvent onmyEvent
click onClick

onSelect は、select でも Select でも呼ばれませんでした。onSelect や onClick は、公式リファレンスにある、すべての要素で使える props の一覧に載っている、React がもともと扱うイベントの名前です。キャメルケースで onSelect と書くと、カスタム要素のイベントとしては扱われませんでした。カスタム要素のイベントは、送る側の名前どおり onselect と書きます。

React 18 で同じことをすると、呼ばれたのは click のときの onClick だけでした。onselect などの関数は、属性にもなりませんでした。

表のとおり、onselectCapture のように末尾に Capture を付けたハンドラーは、onselect より先に呼ばれました。描き直しでハンドラーを別の関数に替えると、次の select では新しい関数だけが呼ばれ、前の関数は呼ばれませんでした。

TypeScript で型を付ける

TypeScript では、そのままだと JSX に <user-card> を書けません。型の宣言がないと、tsc で次のエラーになりました。

text
src/App.tsx(15,7): error TS2339: Property 'user-card' does not exist on type 'JSX.IntrinsicElements'.
src/App.tsx(18,20): error TS7006: Parameter 'e' implicitly has an 'any' type.

React 19 のアップグレードガイドにある、TypeScript の JSX 名前空間についての説明のとおり、declare module で react の JSX.IntrinsicElements にタグを足します。

ts
// jsx.d.ts
import type { DetailedHTMLProps, HTMLAttributes } from 'react';
import type { User } from './user-card';

type UserCardProps = DetailedHTMLProps<HTMLAttributes<HTMLElement>, HTMLElement> & {
  user?: User | null;
  size?: 'small' | 'large';
  onselect?: (event: CustomEvent<User | null>) => void;
};

declare module 'react' {
  namespace JSX {
    interface IntrinsicElements {
      'user-card': UserCardProps;
    }
  }
}

ふつうの HTML 要素と同じ className や id も書けるように、HTMLAttributes と合わせています。onselect の引数を CustomEvent<User | null> にしておくと、e.detail に型が付きます。宣言を足すとエラーはなくなりました。宣言にない size2="x" を書くと、「Property 'size2' does not exist on type 'UserCardProps'. Did you mean 'size'?」というエラーになりました。

アップグレードガイドでは、declare module に書くモジュール名は、tsconfig.json の jsx の設定によって変わると説明されています(react-jsx なら react/jsx-runtime)。検証環境(@types/react 19.3.0、"jsx": "react-jsx")では、'react' に書いた宣言で型チェックが通りました。

サーバーで描画したときの出力

React 19 のリリースの記事では、サーバーでの描画では、文字列や数値、true は属性として出力し、オブジェクトや関数、false は出力しないと説明しています。react-dom/server の renderToString で、<user-card> に次の props を渡して確かめました。Node.js でそのまま動かせるように、JSX を使わずに createElement で書いています。

js
// ssr.mjs
import { createElement as h, version } from 'react';
import { renderToString } from 'react-dom/server';
console.log('react', version);
console.log(renderToString(h('user-card', { user: { name: 'たま' }, size: 'large', count: 3, flag: true, off: false, onselect: () => {}, className: 'card' })));

出力の HTML は次のとおりです。上が React 19、下が React 18 です。

html
<user-card size="large" count="3" flag="" class="card"></user-card>
<user-card user="[object Object]" size="large" count="3" flag="true" off="false" className="card"></user-card>

React 19 では、user(オブジェクト)、off(false)、onselect(関数)は HTML に出ませんでした。サーバーが返す HTML に含めたい値は、文字列か数値の属性で渡せるようにしておきます。

カスタム要素から className を外すと、class が「undefined」になる

検証用のカスタム要素 <rem-el> に className を渡しておき、次の描画で className を渡さないようにしたところ、要素は <rem-el id="r" class="undefined"></rem-el> になりました。title でも同じで、title="undefined" が残りました。ふつうの <div> で同じことをすると、class 属性は消えました。

className や title は、どの HTML 要素にもあるプロパティです。外した後に要素の title プロパティを読むと、文字列の「undefined」でした。自分で用意したプロパティ(obj など)は、外すと値が undefined になりました。

条件によって className を付けたり外したりするときは、外す代わりに空文字を渡すと、class="" になりました。

tsx
<user-card className={active ? 'card active' : ''} />

​Posted by 86