<dialog>要素

Technical Summary

Definition / Categories

項目	仕様上の整理
意味	作業または情報取得のための一時的なdialog box
Categories	Flow content、Interactive content、Palpable content
Context	Flow contentが期待される場所
Content model	Flow content
Content attributes	Global attributes、closedby、open
DOM interface	HTMLDialogElement。open、returnValue、show()、showModal()、close()、requestClose()

open状態と表示メソッド

openはdialogがactiveで利用者と相互作用できることを表すboolean attributeです。ただし、openの有無だけでは、dialogがmodalかどうかは判定できません。

操作	仕様上の境界
show()	dialogを非modalで表示し、ページの他の部分も相互作用可能にする
showModal()	dialogをtop layerに追加し、最上位のmodal dialogとして表示する
close(result)	dialogを閉じ、指定されたresultをreturnValueへ反映し、close eventを発火する
requestClose(result)	cancel eventを経由するclose requestを行い、キャンセルされなければ閉じる

const dialog = document.querySelector('#settings');

dialog.show();       // non-modal
dialog.close('done');

dialog.showModal();  // modal, top layer
dialog.requestClose('cancel');

Modal・top layer・inert

showModal()で表示されたdialogは、Documentのopen dialogs listに入り、modalとして扱われます。Documentはdialogによってblockされ、dialogの外側のfocused areaはinertになります。dialogはtop layerに置かれるため、通常の祖先要素のz-indexだけで表示順を理解することはできません。

背面に表示される領域は::backdropでスタイルを指定できます。ただし、暗い背景を描くだけではmodalの意味やキーボード操作は実装されません。表示方法、フォーカス、閉じる条件を一体として確認します。

<dialog id="confirm" aria-labelledby="confirm-title">
  <h2 id="confirm-title">削除を確認</h2>
  <p>この操作は取り消せません。</p>
  <form method="dialog">
    <button type="submit" value="cancel" autofocus>キャンセル</button>
    <button type="submit" value="delete">削除する</button>
  </form>
</dialog>

<style>
  #confirm::backdrop { background: rgb(0 0 0 / 0.45); }
</style>

Focus・close request・event

dialog focusing stepsは、autofocus、focus delegate、dialog自身の順に初期フォーカスの候補を探します。利用者が最初に操作する要素が明確なら、dialogの子孫へautofocusを指定して意図を明示します。modalを閉じると、以前にfocusされていた要素へ戻す処理が試みられます。

close()は直接閉じる処理です。requestClose()は、まずcancel eventを発火し、preventDefault()でキャンセルされなければclose処理へ進みます。Escapeキーや閉じる操作を、すべて同じclose requestとして扱う場合に境界を記録できます。

dialog.addEventListener('cancel', (event) => {
  if (mustConfirm) event.preventDefault();
});

dialog.addEventListener('close', () => {
  console.log(dialog.returnValue);
});

closedbyとlight dismiss

closedbyは、利用者のどの操作がdialogを閉じるかを指定するenumerated attributeです。

値	Close条件
any	close requestに加え、dialogの外側のクリックでも閉じる
closerequest	close requestで閉じるが、外側のクリックでは閉じない
none	利用者操作による自動closeを行わない
省略または不正値	Auto。modalの表示方法などの条件からcomputed closed-by stateが決まる

この属性の実装状況や外側クリックの扱いは、ブラウザー・確認時点・表示方法に依存し得ます。仕様の値と、実際に観測したclose条件を混同しません。

Form method="dialog"とreturnValue

formのmethodがdialog状態の場合、form submissionはネットワーク送信ではなく、formを含むdialogを閉じる処理になります。submitterが持つ値がdialogのreturnValueへ渡されます。

<dialog id="ship">
  <form method="dialog">
    <button type="submit" value="board">乗船する</button>
    <button type="submit" value="call">船長を呼ぶ</button>
  </form>
</dialog>

ship.addEventListener('close', () => {
  if (ship.returnValue === 'board') {
    // 選択に応じた処理
  }
});

DOM Interface

HTMLDialogElement.openはopen属性をbooleanとして反映します。returnValueは直近のclose resultを返します。表示・終了の意味を、単なる属性の付け外しと同一視しないことが重要です。

const dialog = document.querySelector('#settings');

dialog.open;
dialog.returnValue;
dialog.show;
dialog.showModal;
dialog.close;
dialog.requestClose;

Fact / Evidence（主張 / 根拠）

dialogの意味、表示方法、modal状態、focus、close request、form境界を、適用条件・確認状態・根拠位置に分けて記録します。ブラウザーの実際の表示・focus・Accessibility Treeは下のImplementation Evidenceへ分離します。

Evidence

1. HTML Standard: The dialog element — 意味、categories、content model、open、closedby、focus、show、showModal、close、requestClose、top layer
2. HTML Standard: Form control infrastructure — method="dialog"、submitter、dialog close、return value
3. HTML Accessibility API Mappings — dialogのrole、accessible name、stateとplatform API mappingの確認入口
4. Web Platform Tests: the-dialog-element — dialog、modal、focus、close、toggleに関係するテスト群の入口

Implementation Evidence

仕様上の主張とは別に、ブラウザー実装・WPT・Accessibility Treeの観測を記録します。dialog-v1をChrome 153で実行し、IMPLとAccessibility Treeの部分観測結果を登録しました。未確認の項目を確認済みとは扱いません。

専用fixture: dialog-v1は、non-modal / modal表示、初期focus、focus復元、close request、method="dialog"、closedby、returnValueを再現するfixtureです。fixture本体はリポジトリのdocs/atlas/dialog-v1-fixture.htmlとdialog-v1-check.js、実行記録はdocs/atlas/dialog-v1-results-2026-09-19.mdに登録しています。

dialogの表示位置、backdrop、Escape、外側クリック、focus、Accessibility Treeの公開はuser agent・OS・属性値・表示方法に依存し得ます。1環境の観測を、すべてのブラウザーに共通する結果として登録しません。

Coverage / Open Issues

• 確認済み意味、Categories、Context、Content model、content attributes、DOM interface
• 確認済みshow() / showModal()、modal blocking、top layer、focus、close request、method="dialog"の仕様上の入口
• 確認済みclosedbyの値、computed closed-by state、light dismissの仕様上の境界
• 部分確認Chrome 153 / Windows NT 10.0でdialog-v1の9項目、名前付きmodal / non-modalのAccessibility Treeと初期focusを確認
• 未完了Firefox・Safariを含むfocus、Escape、backdrop、外側クリック、close event、focus復元の比較
• 未完了closedby、command / commandfor、nested dialog、popoverとの相互作用、実装時期と互換性
• 未完了WPTの個別実行結果、HTML-AAMの全mapping、支援技術別の観測

このページは初期Coverageです。仕様上の処理モデルを整理したものであり、すべてのブラウザーで同じ表示・focus・close条件・アクセシビリティAPI結果になること、またdialog要素全体の検証が完了したことを主張しません。

Related surface

初心者向けのdialogの使い方、モーダル、フォーカス、method="dialog"はYugienのdialog要素ページを参照してください。開く操作はbutton要素、追加情報の開閉との境界はdetails要素、フォーム送信の共通処理はform要素でも確認できます。