React Reference ยท Built-in DOM Components
The dialog element in React
Reference for the HTML dialog element in React: open it as a modal with a ref and showModal(), close it, read the result, and avoid the open-prop trap.
<dialog> is the browser's built-in dialog box. Opened as a modal, it sits in the top layer above the page, blocks interaction with everything behind it, traps focus, closes on Escape and draws a ::backdrop. You get all of that without a library, and without writing focus-management code.
React renders <dialog> like any other element, but opening it as a modal is an imperative call on the DOM node: dialog.showModal(). So the usual pattern is a ref, plus event props for onClose and onCancel. The open prop also exists, but it opens the dialog in the non-modal way, which is rarely what you want.
const ref = useRef(null); <button onClick={() => ref.current.showModal()}>Open</button> <dialog ref={ref} onClose={() => console.log('closed')}> <form method="dialog"><button>Close</button></form> </dialog>
Try it
Syntax
<dialog ref={dialogRef} onClose={handleClose} onCancel={handleCancel} > {children} </dialog>
| Name | Description |
|---|---|
open |
Boolean attribute. When true, the dialog is shown non-modally (no backdrop, no focus trap). It is not the way to open a modal. |
onClose |
Called after the dialog closes by any route: close(), a method="dialog" form, or the Escape key. |
onCancel |
Called when the user asks to dismiss the dialog (Escape key, or the close request on supporting platforms), before it closes. Call event.preventDefault() to keep it open. |
ref |
Gives you the DOM node with showModal(), show(), close(returnValue) and returnValue. |
Returns: a <dialog> element. The methods above belong to HTMLDialogElement, not to React.
Errors: showModal() throws an InvalidStateError if the dialog is already open non-modally, and show() on a modal does too. Calling showModal() on a dialog that is not in the document also throws.
Usage notes
- Do not drive a modal with the
openprop.<dialog open>skips the top layer, the backdrop and focus handling. UseshowModal()for modals; reserveopenfor simple non-modal panels. - A form with
method="dialog"closes the dialog when submitted, and the value of the clicked submit button becomesdialog.returnValue. React does not intercept this, so noonSubmithandler is needed for the simple case. - State can drift. Escape and backdrop-style dismissal close the dialog without touching React state. Listen to
onCloseand update your state there, as the second example does. - Content stays mounted while closed. A closed
<dialog>is hidden with CSS but its children are still rendered. For heavy contents, render them only whenopenis true. - Style the backdrop in CSS with
dialog::backdrop. Inline styles cannot target pseudo-elements. - Initial focus goes to the first focusable element, or to the one with the
autofocusattribute. Closing returns focus to the element that opened the dialog. - Alternatives. For a floating, non-blocking panel the
popoverattribute is simpler. For modals that must render outside a clipped parent, a dialog in the top layer already escapesoverflow: hidden, which removes most reasons to use a portal.
Related
ref, popover attributes, inert,<form>- Lessons: Portals, Accessibility