Skip to content
Tutorials Center
My learning

Topics

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.

JSX
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

A modal with a result
Keeping state in sync with onClose

Syntax

JSX
<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 open prop. <dialog open> skips the top layer, the backdrop and focus handling. Use showModal() for modals; reserve open for simple non-modal panels.
  • A form with method="dialog" closes the dialog when submitted, and the value of the clicked submit button becomes dialog.returnValue. React does not intercept this, so no onSubmit handler is needed for the simple case.
  • State can drift. Escape and backdrop-style dismissal close the dialog without touching React state. Listen to onClose and 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 when open is 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 autofocus attribute. Closing returns focus to the element that opened the dialog.
  • Alternatives. For a floating, non-blocking panel the popover attribute is simpler. For modals that must render outside a clipped parent, a dialog in the top layer already escapes overflow: hidden, which removes most reasons to use a portal.