HTML details and dialog: distinguish disclosure from a modal task

Use it for a real task

A receipt page uses details for a short policy note. The dialog snippet shows static non-modal content using open, which is useful for demonstrating its structure. A production modal requires an owner to invoke showModal, handle close, and restore focus to the initiating control.

<details>
  <summary>What appears in the export?</summary>
  <p>Only approved receipts in the selected batch.</p>
</details>
<dialog open aria-labelledby="review-title">
  <h2 id="review-title">Review receipt R-47</h2>
  <p>This open attribute alone does not make the dialog modal.</p>
</dialog>

What the markup guarantees

Do not treat dialog open as equivalent to a modal focus trap. A dialog launched with JavaScript needs an explicit close path and a tested focus return. For a plain expandable explanation, details is the lighter choice.

Cost and limits

details works without an application script. Modal orchestration adds code and interaction testing; choose it only when interruption and focus management are part of the task.

Common Mistakes

Do not nest a button in summary just to create disclosure behavior.
Do not assume open makes a dialog modal.
Test keyboard close and focus return in a real modal flow.

Connected lessons

Continue with HTML dialog commands: open and request close with named buttons.

Continue with HTML dialog closedby: choose whether outside clicks dismiss a panel.

Style this pattern

Rendering decisions

CSS transform-origin: move a visual pivot without moving the layout box

CSS behavior decisions

Related CSS decisions

CSS ::backdrop: dim a modal without faking modality

Related CSS decisions

CSS :open: style the native open state without inventing one