自作のモーダルは、Escで閉じずキーボードでも操作できません。UIライブラリとヘッドレスUIの違いと、自分で作るときに抜ける点を見ます。
これは深掘りです。本線の順路ではありません。 本線のアクセシビリティの回で「<div> に onClick を付けたものはボタンではない」をやり、デザインシステムの回で自分の Button を1つ作ったあと、「モーダルも自分で作ればいいのでは」と思った人が読む記事です。飛ばしても本線は進みます。
この記事のコマンドは、すべて VM(Ubuntu Server)の中で打ちます。 Windows の PowerShell ではありません。 画面の確認は、ホストの Windows のブラウザで行います。 本線で作った
~/react-demo/には触りません。 この記事では、まっさらな~/reactlab/を新しく作って、最後に丸ごと消します。
自分が実際にぶつかったところから書きます。
削除の確認ダイアログが要りました。「本当に削除しますか?」の、あれです。
ライブラリを入れるほどのものではないと思いました。 デザインシステムの回で Button を自分で作ったばかりで、その延長のつもりでした。
書いたのは、これだけです。
const [open, setOpen] = useState(false);
{open && (
<div className="overlay">
<div className="modal">
<p>本当に削除しますか?</p>
<button onClick={() => setOpen(false)}>キャンセル</button>
</div>
</div>
)}
動きました。 ボタンを押すと出て、キャンセルを押すと消えます。見た目も、そこそこ整いました。
そのあと、アクセシビリティの回で覚えた確認をやりました。マウスから手を離して、キーボードだけで触る、というやつです。
何も、できませんでした。
- Esc キーを押しても、閉じません
- 開いた直後、Tab を押すと、モーダルではなく後ろのページのリンクにフォーカスが行きます
- Tab を押し続けると、モーダルを飛び越えて、背後の画面を延々と巡ります
- 背景を触ると、後ろのページがスクロールします
つまり、キーボードだけで使っている人にとって、これは「画面の上に絵が乗っただけ」でした。
ここで分かったことがあります。
モーダルの難しさは、見た目ではありません。振る舞いです。 そして振る舞いのほとんどは、アクセシビリティの話です。
この記事では、足りないものを7個のチェックリストにして、1つずつ数えます。 そのうえで、ブラウザ標準の <dialog> で何個消えるか、ヘッドレスUIを1つ入れると何個消えるかを、同じ部品で並べます。
対象レベル: 中級〜上級 / 区分: 発展
この記事でわかること
- モーダルで難しいのは見た目ではなく振る舞いであること。足りないものは、数えると7個ある
- その7個のほとんどは、ブラウザに最初から入っていること。
<dialog>とshowModal()で5個が消える - ヘッドレスUIは「見た目が無いUIライブラリ」ではないこと。見た目を持たず、振る舞いとアクセシビリティだけを提供するもの
- UIライブラリは3種類に分かれること(全部入り / ヘッドレス / コピーして使う)。どれが上ということはなく、向き不向きがある
- 「軽いから」でライブラリを選ばないこと。確認するのは5項目で、いちばん大事なのは抜けられるかどうか
- 自作は「安く済ませる方法」ではないこと。正しく作ろうとすると、自作がいちばん高くつく
この記事でやること
~/reactlabを新しく作る(本線の~/react-demoは残したまま)。ポートは 5185- とりあえず動くモーダルを自作して、足りないものを7項目のチェックリストで数える
- キーボードだけで触って、実際に足りないことを確かめる
- 同じものを
<dialog>で書き直して、チェックリストがいくつ埋まるかを見る - ヘッドレスUIを1つ入れて、3つ目のモーダルを作り、残りが埋まることを確かめる
- 3分類の表と、入れる前に確認する5項目で、自分の判断を決める
~/reactlabを消して片づける
先に知る言葉
この記事で初めて出てくる言葉です。 基本的な言葉は用語集にもまとめてあります。
| 言葉 | 意味 |
|---|---|
| モーダル | 後ろの画面を操作できなくして、前面に出す小窓。「本当に削除しますか?」のあれ。閉じるまで先へ進めないので modal(様式を切り替える)と呼ぶ |
| フォーカス | いまキーボードの入力を受け取っている場所。Tab キーで移っていく、あの枠 |
| フォーカストラップ | 開いている小窓の外へ Tab で出られないようにすること。最後の要素の次が、先頭に戻る |
<dialog> | ブラウザに最初から入っている小窓用のHTMLタグ。JS から showModal() で開く |
| トップレイヤー | ブラウザが持つ全部より前面の層。showModal() で開いた <dialog> はここに置かれ、z-index の勝負から降りられる |
inert | その要素を「無いもの」として扱わせる指定。クリックもフォーカスも当たらなくなる |
| ヘッドレスUI | 見た目(head)を持たず、振る舞いだけを提供するUIライブラリ。CSSは自分で当てる |
| スクリーンリーダー | 画面の内容を音声で読み上げるソフト。目が見えない人が使う。何が「いま前面にある小窓か」を、機械が判断できないと読めない |
role="dialog" / aria-modal | 「これは小窓です」「後ろは触れません」と機械に伝えるための属性。見た目は1ミリも変わらない |
| バンドルサイズ | ライブラリを入れた結果、読者のブラウザに送られるJSの量。増えるほど、遅い回線での初回表示が遅れる |
① 準備 — reactlab を新しく作る
本線で作った ~/react-demo/ は、そのまま残します。 この記事はわざと壊れたモーダルを作る手順を含むので、新しいプロジェクトでやります。
VMの中で打ちます。
質問が出たら、そのまま Enter で構いません。 版によっては「このまま npm install して起動しますか?」と聞かれます。そこは No(n)を選んでください。 ポートを自分で決めたいからです。
eslint.config.js index.html package.json public README.md src vite.config.js
この一覧が出れば成功です。 npm install は初回だけ数分かかります。何が起きているかはnpmの回にあります。
ポートを開ける
本線で 5173番を使っています。 ぶつからないように、この記事は 5185番でやります。
Status: active
To Action From
-- ------ ----
22/tcp ALLOW Anywhere
5173/tcp ALLOW Anywhere
5185/tcp ALLOW Anywhere
5185/tcp の行が出れば準備完了です。開けずに起動すると、ターミナルには「起動しました」と出るのに、ブラウザは読み込み中のままになります。
起動する
ホストの Windows のブラウザで http://192.168.226.50:5185/ を開いてください(IPは自分の値に。分からなければ VM の中で ip a)。Vite のロゴとカウンターが出れば成功です。
止め方: ターミナルで Ctrl+C。この記事の間は起動したままで構いません。 保存するたびにブラウザが自動で更新されます。
[スクリーンショット: 01_reactlab起動.png] ホストのブラウザで :5185 を開き、Vite + React の初期画面が出ているところを撮ってください。アドレスバーのポート番号が 5185 になっているのが見える形で。
背景を用意する — 「後ろに何かある」状態を作る
モーダルの検証は、後ろに触れるものが無いと成立しません。 Tab がどこへ逃げるかを見たいからです。
src/App.jsx(まるごと入れ替え)
import { useState } from "react";
import PlainModal from "./PlainModal";
export default function App() {
const [log, setLog] = useState([]);
return (
<div>
<h1>モーダルの比較</h1>
<PlainModal onDelete={() => setLog((l) => [...l, "自作版で削除した"])} />
<hr />
<h2>背景のコンテンツ</h2>
<p>
<a href="https://example.com">背景のリンク1</a>{" "}
<a href="https://example.com">背景のリンク2</a>
</p>
<p>
<input type="text" placeholder="背景の入力欄" />{" "}
<button type="button">背景のボタン</button>
</p>
<div style={{ height: "1200px", background: "#f3f3f3" }}>
<p>ここは縦に長い領域です。背景がスクロールするかどうかの確認に使います。</p>
</div>
<ul>
{log.map((line, i) => (
<li key={i}>{line}</li>
))}
</ul>
</div>
);
}
key={i} にしているのは、追記しかしないログだからです。理由はkeyの回にあります。
src/index.css を、まるごとこの内容にしてください。中身は本題ではありません。
body {
font-family: sans-serif;
margin: 0;
padding: 24px;
background: #fff;
color: #222;
}
.overlay {
position: fixed;
inset: 0;
background: rgba(0, 0, 0, 0.5);
display: grid;
place-items: center;
}
.modal {
background: #fff;
border-radius: 8px;
padding: 24px;
max-width: 400px;
}
.modal h2 {
margin-top: 0;
}
button {
font-size: 16px;
padding: 6px 14px;
margin-right: 8px;
}
② モーダルを自作して、足りないものを数える
まず、動くものを作る
src/PlainModal.jsx(新規)
import { useState } from "react";
export default function PlainModal({ onDelete }) {
const [open, setOpen] = useState(false);
return (
<div>
<button onClick={() => setOpen(true)}>自作モーダルを開く</button>
{open && (
<div className="overlay">
<div className="modal">
<h2>本当に削除しますか?</h2>
<p>この操作は取り消せません。</p>
<button
onClick={() => {
onDelete();
setOpen(false);
}}
>
削除する
</button>
<button onClick={() => setOpen(false)}>キャンセル</button>
</div>
</div>
)}
</div>
);
}
ブラウザで確認してください。 ボタンを押すと暗い背景の上に白い箱が出て、キャンセルで消えます。
これで「できた」と思ってしまうのが、この記事の入口です。
[スクリーンショット: 02_自作モーダル.png] 自作モーダルを開いた状態を撮ってください。背景が暗くなって、白い箱が中央に出ているところです。
足りないもののチェックリスト
モーダルが満たすべきことを、先に7個書き出します。 これは思いつきではなく、W3C の「ダイアログのパターン」として文書化されているものです(参考リンクに置いてあります)。
| # | 満たすこと | 満たしていないと、誰が困るか |
|---|---|---|
| 1 | Escape キーで閉じる | キーボード利用者。閉じるボタンを探して Tab を延々と押すことになる |
| 2 | 背景(暗い部分)をクリックすると閉じる | 全員。そこを押せば閉じると、みんな思っている |
| 3 | 開いたとき、フォーカスが中に移る | キーボード利用者・スクリーンリーダー利用者。開いたことに気づけない |
| 4 | Tab で外に逃げない(フォーカストラップ) | 同上。見えない場所を操作してしまう |
| 5 | 閉じたとき、開いたボタンにフォーカスが戻る | 同上。フォーカスが先頭に飛ばされて、どこにいるか分からなくなる |
| 6 | 背景がスクロールしない | 全員。特にスマホで、指が背景を動かしてしまう |
| 7 | スクリーンリーダーに「小窓が開いた」と伝わる | スクリーンリーダー利用者。<div> のままでは、ただの文字の塊 |
1つずつ、実際に確かめる
読むだけでは意味がありません。 アクセシビリティの回と同じで、マウスから手を離して確かめます。
手順(すべてホストの Windows のブラウザ側):
- ページを読み込み直す
- Tab を数回押して、「自作モーダルを開く」ボタンに枠が付くところまで進む
- Enter を押して開く
- そのあと、下の表のとおりに押していく
| # | 確かめ方 | この自作版の結果 |
|---|---|---|
| 1 | Escape を押す | 何も起きない |
| 2 | 暗い部分をクリックする | 何も起きない |
| 3 | 開いた直後に Tab を1回押す | モーダルの「削除する」ではなく、背後のリンクに枠が付く |
| 4 | Tab を10回ほど押し続ける | 背景のリンク・入力欄・ボタンを巡って、モーダルの外を延々と回る |
| 5 | キャンセルを押して閉じ、Tab を1回押す | ページの先頭から数え直しになる |
| 6 | 開いたままマウスホイールを回す | 後ろのページがスクロールする |
| 7 | F12 → 要素タブでモーダルの <div> を選ぶ | role が付いていない。ただの div |
7個中、満たしているものは0個です。
「動いている」のは、マウスを持っている人にとってだけでした。
[スクリーンショット: 03_Tabが背景へ逃げる.png] モーダルを開いた状態で Tab を1回押し、背後のリンクにフォーカスの枠が付いているところを撮ってください。枠が暗い背景の下に見えているのが分かる形で。
ここで、自力で埋めようとするとどうなるか
1個ずつ潰していけばいい、と思うはずです。 実際、1番(Escape)だけなら、そう難しくありません。
useEffect(() => {
if (!open) return;
const onKey = (e) => {
if (e.key === "Escape") setOpen(false);
};
document.addEventListener("keydown", onKey);
return () => document.removeEventListener("keydown", onKey);
}, [open]);
return で外しているのが後片づけです。これを忘れると、閉じたあともキーを拾い続けます(useEffect の回)。
問題は4番です。 フォーカストラップを自分で書くと、こういうことを全部考える必要があります。
- モーダルの中でフォーカスできる要素を全部集める(
buttona[href]inputselecttextarea[tabindex]、ただしdisabledとtabindex="-1"は除く) display: noneやvisibility: hiddenで隠れているものは除く(見えないのにフォーカスが行く)- 最後の要素で Tab → 先頭へ、先頭で Shift+Tab → 最後へ
- 中身が後から増えたら、集め直す(読み込み中の表示が消えてボタンが出てくる、など)
<iframe>の中や、埋め込み動画のコントロールはどうするか
そして、これを全部書いても、7番(スクリーンリーダーへの伝達)は別問題です。
自作は、安く済ませる方法ではありません。 「とりあえず動く」が10行で、「使えるものにする」が200行を超えます。
ここで、先に知っておくべきことがあります。 この7個のうち5個は、ブラウザに最初から入っています。
③ <dialog> を使う — ブラウザ標準で大半が片づく
HTML には <dialog> というタグがあります。 名前のとおり、小窓のためのタグです。
普通の要素と違うところは、JS から開く点です。開き方が2つあります。
| 呼び方 | 何が起きるか |
|---|---|
dialog.show() | ただ表示されるだけ。 後ろも普通に触れる(モーダルではない) |
dialog.showModal() | トップレイヤーに置かれ、後ろが inert(無いもの扱い)になる。 これがモーダル |
dialog.close() | 閉じる。close イベントが飛ぶ |
この記事で使うのは showModal() だけです。show() を使うと、見た目は同じなのに、この記事の話が1つも成立しません。
React からどう使うか
ここが引っかかるところです。 React は「state を書き換えたら画面がそうなる」という書き方をします。ところが <dialog> は「メソッドを呼んで開く」という、命令する側の作りです。
噛み合わせるには、useRef の回でやった「DOM を掴む」を使います。
src/DialogModal.jsx(新規)
import { useRef } from "react";
export default function DialogModal({ onDelete }) {
const ref = useRef(null);
return (
<div>
<button onClick={() => ref.current.showModal()}>
dialog版を開く
</button>
<dialog ref={ref} className="modal">
<h2>本当に削除しますか?</h2>
<p>この操作は取り消せません。</p>
<button
onClick={() => {
onDelete();
ref.current.close();
}}
>
削除する
</button>
<button onClick={() => ref.current.close()}>キャンセル</button>
</dialog>
</div>
);
}
{open && ...} が消えたことに注目してください。 <dialog> は常に置いてあって、閉じているときは自分で隠れています。 表示するかどうかを、React の state で持っていません。
App.jsx に足します。
import DialogModal from "./DialogModal";
<PlainModal ... /> のすぐ下に、これを置きます。
<DialogModal onDelete={() => setLog((l) => [...l, "dialog版で削除した"])} />
CSS を少し足します。 暗くする背景は、自分で <div> を作りません。ブラウザが用意しています。
dialog::backdrop {
background: rgba(0, 0, 0, 0.5);
}
dialog {
border: none;
box-shadow: 0 4px 24px rgba(0, 0, 0, 0.3);
}
::backdrop は、showModal() で開いたときだけ現れる疑似要素です。show() では出ません。
もう一度、7個を数える
同じ手順で確かめてください。
| # | 満たすこと | 自作版 | <dialog> 版 |
|---|---|---|---|
| 1 | Escape で閉じる | ❌ | ✅ 何も書いていないのに閉じる |
| 2 | 背景クリックで閉じる | ❌ | ❌ これは付いてこない |
| 3 | 開いたときフォーカスが中に移る | ❌ | ✅ |
| 4 | Tab が外に逃げない | ❌ | ✅ 後ろが inert になるため |
| 5 | 閉じたとき元のボタンに戻る | ❌ | ✅ |
| 6 | 背景がスクロールしない | ❌ | ❌ スクロールできてしまう |
| 7 | スクリーンリーダーに伝わる | ❌ | ✅ role="dialog" と aria-modal は書かなくても付く |
7個中5個が、1行も書かずに埋まりました。
[スクリーンショット: 04_dialogのフォーカス.png] <dialog> 版を開いた直後に Tab を1回押し、フォーカスがモーダルの中のボタンに付いているところを撮ってください。自作版と同じ操作で結果が違うことが分かる形で。
ここが、この記事でいちばん伝えたいところです。 足りないものの大半は、ブラウザが最初から持っていました。 持っていない
<div>で始めたから、全部を自分で書く羽目になっていただけです。
残った2つと、<dialog> の穴
正直に書きます。<dialog> で全部が済むわけではありません。
2番(背景クリックで閉じる) は自前です。::backdrop は疑似要素なので、クリックイベントは <dialog> 自身に飛んできます。 「クリックされた場所が中身の外側か」を測って判断する、という座標計算になります。 新しい closedby="any" 属性なら背景クリックで閉じますが、2026年10月時点で Safari が未対応(Chrome / Edge 134・Firefox 141 以降は対応)なので、まだ座標計算が要ります。
6番(背景スクロール) も自前です。showModal() は後ろを inert にしますが、ページのスクロールまでは止めません。 document.body.style.overflow = "hidden" を開閉に合わせて付け外しすることになり、「閉じ忘れて body がスクロールしなくなる」事故がここで起きます。
さらに、React と組み合わせたときの穴が2つあります。
- Escape で閉じたことを、React は知りません。 閉じたときに state を戻したいなら、
onCloseを自分で拾う必要があります <dialog>の中に<form method="dialog">を置くと、ボタンを押すだけで閉じます。 便利ですが、知らないと「なぜか閉じる」ことになります
onClose を拾う形は、こうです。
<dialog ref={ref} onClose={() => console.log("閉じた")} className="modal">
つまり、<dialog> は「土台としては最良、仕上げは自分」です。
そして、ここまでの作業を思い出してください。 Escape、フォーカス、トラップ、復帰、role。これらは「削除の確認」に固有の話が1つもありません。 どのアプリでも、まったく同じことをやります。
毎回書くもので、毎回同じで、間違えると誰かが使えなくなる。 これは、ライブラリが引き受けるべき仕事です。
④ ヘッドレスUIとは何か
定義から入る
ヘッドレスUI(headless UI)とは、こういうものです。
見た目(スタイル)を一切持たず、振る舞いとアクセシビリティだけを提供するUIライブラリ。
「見た目が地味なライブラリ」ではありません。 見た目が、本当に、1ミリもありません。 入れて素のまま使うと、枠線も背景色も無い、ただの文字が出ます。
では何をくれるのか。 ちょうど、さっき数えた7項目です。
- キーボード操作(Escape、矢印キー、Home/End など、部品ごとに決まった作法)
- フォーカスの管理(移す・閉じ込める・戻す)
- ARIA 属性(
role/aria-modal/aria-labelledbyなどを、正しい組み合わせで) - 開いている・閉じている、選ばれている、といった状態の管理
CSS は自分で当てます。 デザインシステムの回で決めたトークンを、そのまま使えます。見た目の決定権を手放さないまま、振る舞いだけを借りる、という取引です。
入れて、同じモーダルをもう一度作る
Radix UI を使います。 部品ごとにパッケージが分かれているので、ダイアログの1個だけ入れます。
VMの中で、開発サーバーを一度止めて(Ctrl+C)から打ちます。
added 24 packages in 5s
数字は違って構いません。 入ったか確かめます。
reactlab@0.0.0 /home/user/reactlab
└── @radix-ui/react-dialog@1.1.6
版が表示されれば成功です。 起動し直します。
src/HeadlessModal.jsx(新規)
import * as Dialog from "@radix-ui/react-dialog";
export default function HeadlessModal({ onDelete }) {
return (
<Dialog.Root>
<Dialog.Trigger asChild>
<button>ヘッドレス版を開く</button>
</Dialog.Trigger>
<Dialog.Portal>
<Dialog.Overlay className="overlay" />
<Dialog.Content className="modal">
<Dialog.Title>本当に削除しますか?</Dialog.Title>
<Dialog.Description>この操作は取り消せません。</Dialog.Description>
<Dialog.Close asChild>
<button onClick={onDelete}>削除する</button>
</Dialog.Close>
<Dialog.Close asChild>
<button>キャンセル</button>
</Dialog.Close>
</Dialog.Content>
</Dialog.Portal>
</Dialog.Root>
);
}
App.jsx に足します。
import HeadlessModal from "./HeadlessModal";
<HeadlessModal onDelete={() => setLog((l) => [...l, "ヘッドレス版で削除した"])} />
読み方を、上から順に。
| 書いたもの | 意味 |
|---|---|
Dialog.Root | 開いている / 閉じているの状態を持つ入れ物。 ここに state が隠れている |
Dialog.Trigger | 開くためのきっかけ。 クリックと aria-haspopup を面倒みる |
asChild | 「自分でタグを出さず、子に機能だけ渡す」指定。 これが無いと <button> が二重になる |
Dialog.Portal | DOM 上、<body> の直下に出す。 親の overflow: hidden に切られなくなる |
Dialog.Overlay | 暗くする背景。クラス名は自分で決める |
Dialog.Content | 中身。フォーカストラップと Escape は、ここが持っている |
Dialog.Title | タイトル。付けないと開発中に警告が出る。 aria-labelledby の相手になる |
Dialog.Close | 閉じるためのきっかけ |
Dialog.Title を省略すると、コンソールに警告が出ます。 これは親切な仕様です。「小窓に名前が無いと、読み上げソフトは『ダイアログ』としか言えない」からです。警告で強制される、という設計思想がここに出ています。
3度目の、7個
同じ手順で確かめてください。
| # | 満たすこと | 自作 | <dialog> | ヘッドレス |
|---|---|---|---|---|
| 1 | Escape で閉じる | ❌ | ✅ | ✅ |
| 2 | 背景クリックで閉じる | ❌ | ❌ | ✅ |
| 3 | 開いたときフォーカスが移る | ❌ | ✅ | ✅ |
| 4 | Tab が外に逃げない | ❌ | ✅ | ✅ |
| 5 | 閉じたとき元に戻る | ❌ | ✅ | ✅ |
| 6 | 背景がスクロールしない | ❌ | ❌ | ✅ |
| 7 | スクリーンリーダーに伝わる | ❌ | ✅ | ✅ |
| 書いた行数(振る舞いのため) | 0行で0個 | 0行で5個 | 0行で7個 |
7個すべてが、最初から満たされています。
[スクリーンショット: 05_ヘッドレス版.png] ヘッドレス版を開いた状態で、F12 の要素タブでモーダルの要素を選び、role="dialog" と aria-modal="true" が付いているところを撮ってください。
CSS は自分で当てる
気づいたと思いますが、className は自作版とまったく同じ overlay と modal を渡しています。
見た目は、1行も変わっていません。 ライブラリを入れて変わったのは、振る舞いだけです。
これがヘッドレスの意味です。 デザインシステムの回で作ったトークンやクラスを、そのまま渡せます。 Tailwind を使っているなら(Tailwind の回)、ユーティリティクラスをそのまま並べるだけです。
開いている・閉じているに応じた見た目が要るときは、ライブラリが属性を出してくれています。
.modal[data-state="open"] {
animation: fadeIn 150ms ease-out;
}
@keyframes fadeIn {
from { opacity: 0; }
to { opacity: 1; }
}
data-state は Radix が付けているものです。「状態は機械に読める形で外に出す。見た目は書かない」という、ヘッドレスの一貫した態度が、ここにも出ています。
React Aria という選択肢
もう1つの代表が、Adobe の React Aria(react-aria-components)です。 どちらを選んでも、この記事の話は変わりません。違いは、性格です。
| Radix UI | React Aria | |
|---|---|---|
| 出しているところ | WorkOS(元は Modulz が開発) | Adobe |
| 使い勝手 | 部品を組み立てる形。JSX が素直 | 同じく組み立て型だが、フックだけを取り出す道も用意されている |
| 得意 | Web での作法に忠実 | スマホ・タッチ・国際化まで含めて広い(右から左に書く言語、日付の形式など) |
| 入れ方 | 部品ごとに個別のパッケージ | まとめて1つのパッケージ |
この記事では Radix を使いましたが、React Aria でも構いません。 両方入れないでください。 同じ役目のものが2つあると、どちらの作法で書いたか分からなくなります。
⑤ UIライブラリは3種類ある
「UIライブラリ」と一括りに呼ばれていますが、中身は3種類に分かれます。 この分類を知らないまま比較記事を読むと、噛み合いません。
| 全部入り | ヘッドレス | コピーして使う | |
|---|---|---|---|
| 代表 | MUI, Ant Design, Chakra UI | Radix UI, React Aria, Headless UI | shadcn/ui |
| 見た目 | 最初から完成している | 無い。自分で書く | 完成品が、あなたのリポジトリに入る |
| 入れ方 | npm install | npm install | コマンドでソースが src/ にコピーされる |
| 更新 | ライブラリの更新に追従 | 同左 | 自動では来ない。自分のコードだから |
| 見た目を変える | できるが、逆らうと苦しい | 自由。もともと何も無い | 自由。ファイルを直接編集する |
| アクセシビリティ | たいてい面倒をみている | これが本体 | 中身は Radix なので、同等 |
| バンドルサイズ | 大きくなりやすい | 使った部品の分だけ | 使った部品の分だけ |
| 向いている場面 | 見た目にこだわりが無く、速く出したいとき(社内ツール、管理画面) | デザインが先に決まっているとき | ヘッドレスの手間を減らしたいが、中身も触りたいとき |
| 向いていない場面 | 独自デザインを当てたいとき。 逆らうCSSを書き続けることになる | とにかく速く出したいとき。 見た目を全部書く手間がかかる | 更新を自動で受け取りたいとき |
3つ目の「コピーして使う」が分かりづらいので、補足します。
shadcn/ui は、npm でインストールするライブラリではありません。 コマンドを打つと、部品の .jsx ファイルが、あなたのプロジェクトの中にコピーされます。 そこから先はあなたが書いたコードです。自由に書き換えられます。
その代わり、バグ修正も改善も、自動では降ってきません。 「依存を減らす」ではなく、「依存を、更新の責任ごと自分に移す」という取引です。
そして、shadcn/ui の中身は Radix UI です。 つまり3分類は排他ではありません。 ヘッドレスの上に、見た目を乗せて配っているものが、3つ目です。
⑥ 入れる前に確認すること — 5項目
「良さそうだから入れる」をやめます。 ライブラリを入れる判断は、消す判断より、はるかに軽く行われます。
入れる前に、この5つを見ます。
1. バンドルサイズ — 読者が払う代金
あなたのPCは速いです。読者のPCは速くありません。
確かめ方は2つ。
ただし node_modules の大きさは、ブラウザに送られる量ではありません。 そこには README も型定義も、複数の配布形式も入っています。実際に送られる量は、ビルドして測ります(ビルドツールの回)。
入れる前と後で dist/assets の .js を比べてください。 これが、唯一まともな測り方です。 ネット上の「◯KB」は、圧縮の条件も、使った部品の数も違います。
部品ごとにパッケージが分かれているライブラリが有利なのは、ここです。 ダイアログしか使わないなら、ダイアログの分しか増えません。
2. 更新頻度 — 生きているか
GitHub のリポジトリで見ます。
- 最後のコミットはいつか(半年以上動きが無いUIライブラリは、慎重に)
- 未解決の issue が積み上がっていないか。数より、返事が付いているか
- 使っている React の版に対応しているか。 React の大きな更新のたびに、追従できずに脱落するライブラリが出ます
3. アクセシビリティの扱い — 書いてあるか、測っているか
「アクセシブルです」と書いてあるだけのものは、信じません。
見るのは、ここです。
- 各部品のドキュメントに、キーボード操作の表があるか(Escape で何が起きる、矢印キーで何が起きる)
- どの仕様に沿ったか名指ししているか(W3C の ARIA Authoring Practices など)
- 今日やったように、自分で7個を数える。 これがいちばん確実です
4. 見た目を変えられるか — どこまで自由か
全部入りを選ぶときは、必ずここで詰みかけます。
- クラス名を渡せるか。 渡せても、ライブラリのCSSに勝てるか(
!importantを書き始めたら黄信号) - HTMLの構造そのものを変えられるか。 「ボタンの中にアイコンを入れたいだけ」で行き詰まることがあります
- デザイントークンを外から渡せるか(デザインシステムの回で作ったもの)
5. 抜けられるか — いちばん大事
入れるときに考えるのは、やめるときのことです。
- 1部品だけ、自分の実装に差し替えられるか。 全部入りは、たいてい混ぜられません(見た目が揃わない)
- アプリのロジックが、ライブラリの型や作法に染まっていないか
- やめるとしたら、何ファイル触るか。 これを見積もれないなら、まだ入れる段階ではありません
ヘッドレスが有利なのは、この5番目です。 見た目は自分のCSSに残るので、抜けても消えるのは振る舞いだけです。
⑦ 判断 — 何を選ぶか
答えは1つに決まりません。決め方が決まります。
| あなたの状況 | 選ぶもの | 理由 |
|---|---|---|
| デザインが先に決まっている(デザイナーがいる / 自分でトークンを決めた) | ヘッドレス | 見た目の決定権を渡さずに、振る舞いだけ借りられる |
| とにかく速く出したい。見た目は標準的でよい(社内ツール、管理画面、試作) | 全部入り | 考える回数がいちばん少ない。デザインを「決めない」で済む |
| ヘッドレスを使いたいが、毎回CSSを書くのが重い | コピーして使う | 完成品から始めて、要るところだけ書き換える |
| 仕組みを知りたい(この記事のような目的) | 自作 → <dialog> | 足りないものを数えた経験が残る。ただし本番には出さない |
| 部品が1つか2つしか要らない | まず <dialog> と <details> | 入れずに済むなら、それがいちばん軽い |
このサイトの方針
このサイトでは、こう決めました。
- まずブラウザ標準で足りないか見る。
<dialog><details><select>で済むなら、ライブラリを入れない - 足りないと分かったら、ヘッドレスを1つだけ入れる。 このサイトの記事は見た目を自分で決めているので、全部入りは合わない
- 全部入りは入れない。 「仕組みが分かること」を絶対条件にしているのに、中身が見えない完成品を置くと、記事にならないため
- 自作は、記事のためだけにやる。 今日書いた
PlainModal.jsxは、教材であって、成果物ではありません
この1〜4は「正しい方針」ではなく、「このサイトの都合から出た方針」です。 あなたの都合が違うなら、答えも違って構いません。 大事なのは、⑥の5項目を通したかどうかです。
つまずいたところ
Dialog.Trigger の中でボタンが二重になった
最初、asChild を書きませんでした。
<Dialog.Trigger>
<button>開く</button>
</Dialog.Trigger>
F12 で見たら、<button> の中に <button> が入っていました。 Dialog.Trigger が自分でも <button> を出すからです。
<button> の中に <button> は、HTML として不正です。 クリックがどちらに飛ぶかも、読み上げソフトが何と言うかも、保証がありません。
asChild を付けると、Dialog.Trigger は自分のタグを出さず、子に props だけ渡します。 これは Radix 全体の作法なので、Trigger と Close では、ほぼ毎回書きます。
<dialog> を show() で開いて、全部が壊れた
showModal() と show() を打ち間違えました。 見た目は同じように出ます。
ところが、Escape も効かず、Tab は背景に逃げ、背景も暗くなりませんでした。 自作版と、まったく同じ結果です。
show() はモーダルではありません。 ::backdrop も出ません。「暗くならない」と気づいたら、まず綴りを見てください。
背景スクロールを止めたら、二度と戻らなくなった
<dialog> 版で6番を埋めようとして、こう書きました。
document.body.style.overflow = "hidden";
閉じるボタンで戻す処理は書きました。 ところが、Escape で閉じたときは通りませんでした。 close() を呼んでいないからです。
結果、ページ全体がスクロールしない状態で固まりました。 読み込み直すまで直りません。
「開いたら止める」を書いたら、必ず「どんな閉じ方でも戻す」を書きます。 onClose で戻すのが確実です。ヘッドレスに移した理由の半分は、これです。
node_modules の大きさを見て、判断しかけた
du -sh node_modules/@radix-ui が 3MB 近くあって、「重い」と思いました。
間違いです。 そこには、型定義・README・複数の配布形式が全部入っています。ブラウザに送られるのは、その一部です。
npm run build して dist/assets を比べたら、増えたのは十数KBでした。 測る場所を間違えると、判断ごと間違えます。
「アクセシビリティのためにライブラリを入れる」が、逆に聞こえた
最初、この記事の結論は「ライブラリを入れましょう」だと思っていました。
違いました。 <dialog> を知っていれば、7個中5個は、そもそもライブラリなしで埋まります。
入れる理由は「アクセシビリティのため」ではなく、「残った2個と、これから作る他の部品(メニュー・タブ・ツールチップ)のため」です。部品が1つなら、入れない判断のほうが正しいことがあります。
全部入りを試して、CSSで戦いになった
別の日に、全部入りのライブラリで同じ確認ダイアログを作りました。 3分でできました。速さは本物です。
そのあと、角の丸みと影を、このサイトの見た目に合わせようとしました。 そこから1時間、勝てないCSSを書き続けました。
全部入りが遅いのではありません。 「その見た目でよい」なら、いちばん速いです。 「その見た目ではだめ」なとき、いちばん高くつきます。 ⑥の4番を先に見ていれば、最初から選ばなかったはずでした。
後片づけ
開発サーバーを止める
起動しているターミナルで Ctrl+C を押してください。
確認: 何も出なければ、止まっています。
ポートを閉じる
この記事のためだけに開けた 5185番を閉じます。
確認: 5185/tcp の行が消えていれば成功です。5173番は、本線で使うので残してあります。
プロジェクトを消す
~/reactlab/ は、この記事のためだけに作りました。
確認: reactlab が消えて、react-demo が残っていること。
残しておきたい場合は、node_modules だけ消せば数百MB空きます。
戻すときは cd ~/reactlab && npm install だけです。
確認: 本線のファイル一覧が出れば、無事です。~/react-demo/ は絶対に消さないでください。 本線がその続きで進みます。
まとめ
- モーダルの難しさは見た目ではなく振る舞い。足りないものは、数えると7個ある(Escape / 背景クリック / フォーカス移動 / トラップ / 復帰 / 背景スクロール / 機械への伝達)
- 自作した
<div>のモーダルは、7個中0個を満たしていない。 「動いている」のはマウスを持っている人にとってだけ <dialog>をshowModal()で開くと、1行も書かずに5個が埋まる。 足りなかったものの大半は、ブラウザが最初から持っていたshow()はモーダルではない。 綴りを1文字間違えると、::backdropも出ず、フォーカスも閉じ込められない- React から
<dialog>を使うときはuseRefで掴んでshowModal()/close()を呼ぶ。{open && ...}を書かない。表示は state で持たない - Escape で閉じたことを React は知らない。
onCloseを拾わないと、state がずれる <dialog>で埋まらないのは2つ。 背景クリックで閉じる(座標計算が要る)と、背景スクロール(bodyのoverflowを付け外し)bodyのスクロールを止めたら、どんな閉じ方でも必ず戻す。 戻し忘れると、ページ全体が固まる- ヘッドレスUIは「見た目が地味なライブラリ」ではない。見た目が本当に無い。 くれるのは、振る舞い・フォーカス管理・ARIA属性の3つ
- ヘッドレスに替えても、
classNameは自作版と同じで済む。 見た目の決定権を手放さずに、振る舞いだけ借りられる - Radix では
TriggerとCloseにasChildを書く。 忘れると<button>が二重になる Dialog.Titleを省略すると警告が出る。 名前の無い小窓は、読み上げソフトが「ダイアログ」としか言えないため- UIライブラリは3種類。 全部入り(MUI)/ ヘッドレス(Radix・React Aria)/ コピーして使う(shadcn/ui)
- 3分類は排他ではない。 shadcn/ui の中身は Radix。ヘッドレスの上に見た目を乗せて配っている
- 「コピーして使う」は依存を減らすのではなく、更新の責任を自分に移す取引
- 入れる前に確認するのは5つ。 バンドルサイズ / 更新頻度 / アクセシビリティの扱い / 見た目を変えられるか / 抜けられるか
- バンドルサイズを
node_modulesの大きさで測らない。npm run buildしてdist/assetsを、入れる前と後で比べる - 5項目でいちばん重いのは「抜けられるか」。 やめるときに何ファイル触るか見積もれないなら、まだ入れる段階ではない
- 判断は状況で決まる。 デザインが決まっているならヘッドレス / 速さ優先なら全部入り / 学習目的なら自作
- 部品が1つか2つなら、
<dialog>で止めるのがいちばん軽い - 自作は安く済ませる方法ではない。 「とりあえず動く」が10行、「使えるものにする」が200行を超える
参考リンク
- roadmap.sh — React
- MDN — dialog 要素
- MDN — HTMLDialogElement.showModal
- MDN — ::backdrop
- MDN — inert 属性
- Can I use — dialog 要素の対応状況
- W3C — ARIA Authoring Practices: Dialog (Modal) パターン
- React 公式 — useRef
- React 公式 — Manipulating the DOM with Refs
- Radix UI — Dialog
- Radix UI — Composition と asChild
- React Aria Components 公式
- Headless UI 公式
- shadcn/ui 公式
- MUI 公式
- Vite 公式ドキュメント
次に読む
この記事は 【深掘り】React の 16 / 24 本目です。
| 記事 | |
|---|---|
| ← 前の記事 | Reactのスタイリング — CSSの当て方を1つに決める |
| → 次の記事 | 状態管理ライブラリ — 入れる前に大半は要らなかった |
上から順に読めば積み上がるように並べています。 飛ばしても構いませんが、詰まったら前の回に戻ってください。
全体の順路は はじめに にあります。
roadmap.sh のどこをやっているか
- 自作モーダルに足りない7項目
- ヘッドレスUIと全部入りの使い分け
この記事は、上の項目を実際に手を動かして確かめる回です。

コメント