Skip to content

Dialog (Modal)

Dialog - DialogOverlay - DialogContent

An accessible dialog or "modal" window.

Installation

npm install @reach/dialog
# or
yarn add @reach/dialog

And then import the components you need:

import { Dialog, DialogOverlay, DialogContent } from "@reach/dialog";

Dialog

High-level component to render a modal dialog window over the top of the page (or another dialog).

<Dialog>
  <p>Some Content</p>
</Dialog>

Dialog Props

PropType
element propsspread
isOpenbool
onDismissfunc
childrennode

Dialog element props

Type: spread

Any props not listed above will be spread onto the underlying DialogContent element, which in turn is spread onto the underlying div[data-reach-dialog-content].

Dialog isOpen

Type: bool default: true

Controls whether the dialog is open or not.

<Dialog isOpen={true}>
  <p>I will be open</p>
</Dialog>

<Dialog isOpen={false}>
  <p>I will be closed</p>
</Dialog>

If you'd rather not have the dialog always rendered, you can put a guard in front of it and only render when it should be open. In this case you don’t need the isOpen prop at all.

Note, however, that the dialog will not render to the DOM when isOpen={false}, but you may want to save on the number of elements created in your render function. You should probably do this when your dialog contains a lot of elements.

Dialog onDismiss

Type: func: (event) => void

This function is called whenever the user hits "Escape" or clicks outside the dialog. It's important to close the dialog onDismiss as seen in all the demos on this page.

The only time you shouldn't close the dialog on dismiss is when the dialog requires a choice and none of them are "cancel". For example, perhaps two records need to be merged and the user needs to pick the surviving record. Neither choice is less destructive than the other, in these cases you may want to alert the user they need to a make a choice on dismiss instead of closing the dialog.

Dialog children

Type: node

Accepts any renderable content.

<Dialog>
  <p>Anything you want, you got it.</p>
</Dialog>

DialogOverlay

Low-level component if you need more control over the styles or rendering of the dialog overlay.

Note: You must render a DialogContent inside.

DialogOverlay CSS Selectors

Please see the styling guide.

Use the following CSS to target the overlay:

[data-reach-dialog-overlay] {
  background: hsla(0, 0%, 0%, 0.2);
}

DialogOverlay Props

PropType
element propsspread
isOpenbool
onDismissfunc
initialFocusRefref
childrennode

DialogOverlay element props

Type: spread

Any props not listed above will be spread onto the underlying div.

<DialogOverlay className="light-modal">
  <p>The underlying element will receive a class</p>
</DialogOverlay>

DialogOverlay isOpen

Type: bool

Same as Dialog isOpen

DialogOverlay onDismiss

Type: func

Same as Dialog onDismiss

DialogContent initialFocusRef

Type: ref

By default the first focusable element will receive focus when the dialog opens but you can provide a ref to focus instead.

DialogOverlay children

Type: node

Should be a DialogContent.

<DialogOverlay>
  <DialogContent>Hey!</DialogContent>
</DialogOverlay>

DialogContent

Low-level component if you need more control over the styles or rendering of the dialog content.

Note: Must be a child of DialogOverlay.

Note: You only need to use this when you are also styling DialogOverlay, otherwise you can use the high-level Dialog component and pass the props to it. Any props passed to Dialog component (besides isOpen and onDismiss) will be spread onto DialogContent.

DialogContent CSS Selectors

Please see the styling guide.

Use the following CSS to target the overlay:

[data-reach-dialog-content] {
  border: solid 5px hsla(0, 0%, 0%, 0.5);
}

DialogContent Props

PropType
element propsspread
childrennode

DialogContent element props

Type: spread

Any props not listed above will be spread onto the underlying div.

<DialogContent className="nice-border">
  <p>The underlying element will receive a class</p>
</DialogOverlay>

DialogContent children

Type: node

Accepts any renderable content.

<DialogContent>
  <p>Anything you want, you got it.</p>
</DialogContent>

Animation Example

If you'd like to animate the content, give React Spring a shot.

Accessibility

Tabbable Elements

It is recommended to have at least one tabbable element in the dialog content. Ideally the first element in the dialog is a close button. If no tabbable elements are found, the dialog content element itself will receive focus.

Labeling

As with many other complex UI components, a dialog needs to be properly labeled to provide context for users with assistive technology such as screen readers. If a dialog is announced to the user without a label, it can be confusing and difficult to navigate.

There are two general approaches to labeling UI components on the web: aria-label and aria-labelledby. If the text of the is visible on screen, you should provide the label's HTML element with a unique id attribute. That id value is then given to an aria-labelledby attribute (or in React, an aria-labelledby prop) on the Dialog. With this context, the screen reader will announce whatever text is nested inside that ID'd markup as the title for the Dialog.

Alternatively, a design may not include a visible label on the screen, but this context is still important for non-sighted users. In this case, you need to provide an aria-label prop to your Dialog instead.

With aria-label

function Example(props) {
  return (
    <Dialog aria-label="Warning about next steps" isOpen={true}>
      <p>This might take a while! Are you sure?</p>
      <button>Go Forward</button> <button>Go Back</button>
    </Dialog>
  );
}

With aria-labelledby

function Example(props) {
  const labelId = `label--${useId(props.id)}`;
  return (
    <Dialog aria-labelledby={labelId} isOpen={true}>
      <h1 id={labelId}>Next Steps</h1>
      <p>Follow these steps carefully!</p>
      <button>Go Forward</button> <button>Go Back</button>
    </Dialog>
  );
}

NOTE: American users may see aria-labelledby and suspect a typo. In some regions (including the UK and Great Britain), the word is indeed spelled labelled instead of labeled. The correct HTML attribute is aria-labelledby.

For more details, see the W3C recommendations for aria-label.

Aria Hiding Other Elements

The aria role "dialog" has been problematic in the past with the virtual cursor, effectively hiding a lot of dialog content from screenreader users. Instead, Dialog will set aria-hidden on all nodes at the document.body root except for the currently active dialog. This traps the virtual cursor inside the dialog.

This is a little unusual for a React component to traverse the DOM that it isn't a part of. Care has been taken to restore the manipulated attributes back to their original values.

Keyboard Accessibility

keyaction
EscapeDismisses the dialog (if the app allows)

Z Index Wars

Dialog does not set a z-index, it depends on the DOM order to be on top of the rest of the app (the overlay is inserted at the end of the document when it is opened). If your app is already battling in the z-index wars, be sure to add a z-index to the <Dialog> or <DialogOverlay> that you render.