useDialog

Provides the behavior and accessibility implementation for a dialog component. A dialog is an overlay shown above other content in an application.

install	`yarn add react-aria`
version	3.19.0
usage	`import {useDialog} from 'react-aria'`

View ARIA pattern

W3C

API#

useDialog(
  (props: AriaDialogProps,
  , ref: RefObject<FocusableElement>
)): DialogAria

Features#

The HTML <dialog> element can be used to build dialogs. However, it is not yet widely supported across browsers, and building fully accessible custom dialogs from scratch is very difficult and error prone. useDialog, combined with useModal, helps achieve accessible dialogs that can be styled as needed.

Exposed to assistive technology as a dialog or alertdialog with ARIA
Handles labelling the dialog by its title element
Handles focusing the dialog on mount, unless a child element is already focused
Contains focus inside the dialog when combined with <FocusScope>
Hides content behind the dialog from screen readers when combined with useModal
Prevents scrolling the page behind the dialog when combined with usePreventScroll
Handles closing the dialog when interacting outside and pressing the Escape key, when combined with useOverlay

Anatomy#

A dialog consists of a container element and an optional title. useDialog handles exposing this to assistive technology using ARIA. It can be combined with useModal, usePreventScroll, and useOverlay as needed to create modal dialogs, popovers, and other types of overlays.

useDialog returns props that you should spread onto the appropriate element:

Name	Type	Description
`dialogProps`	`DOMAttributes`	Props for the dialog container element.
`titleProps`	`DOMAttributes`	Props for the dialog title element.

If a dialog does not have a visible title element, an aria-label or aria-labelledby prop must be passed instead to identify the element to assistive technology.

Example#

This example shows how to build a typical modal dialog. It has a partially transparent backdrop above the rest of the page, prevents scrolling the body using usePreventScroll, and hides content outside the dialog with useModal.

The modal can be closed by clicking or interacting outside the dialog if the isDismissable prop is set to true, or by pressing the Escape key. This is handled by useOverlay.

Focus is contained within the dialog while it is open using a <FocusScope>. In addition, the first focusable element is automatically focused when the dialog opens, and focus is restored back to the button that opened it when it closes.

The application is contained in an OverlayProvider, which is used to hide the content from screen readers with aria-hidden while a modal is open. In addition, each modal must be contained in an OverlayContainer, which uses a React Portal to render the modal at the end of the document body. If a nested modal is opened, then the first modal will also be set to aria-hidden, so that only the top-most modal is accessible.

Note: useModal only hides content within parent OverlayProvider components. However, if you have additional content in your application outside any OverlayProvider, then you should use the @react-aria/aria-modal-polyfill package to ensure that this content is hidden while modals are open as well. See the watchModals docs for more information.

import {FocusScope, OverlayContainer, OverlayProvider, useDialog, useModal, useOverlay, usePreventScroll} from 'react-aria';

import {useOverlayTriggerState} from 'react-stately';

// Reuse the Button from your component library. See below for details.
import {Button} from 'your-component-library';

function ModalDialog(props) {
  let { title, children } = props;

  // Handle interacting outside the dialog and pressing
  // the Escape key to close the modal.
  let ref = React.useRef();
  let { overlayProps, underlayProps } = useOverlay(props, ref);

  // Prevent scrolling while the modal is open, and hide content
  // outside the modal from screen readers.
  usePreventScroll();
  let { modalProps } = useModal();

  // Get props for the dialog and its title
  let { dialogProps, titleProps } = useDialog(props, ref);

  return (
    <div
      style={{
        position: 'fixed',
        zIndex: 100,
        top: 0,
        left: 0,
        bottom: 0,
        right: 0,
        background: 'rgba(0, 0, 0, 0.5)',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center'
      }}
      {...underlayProps}
    >
      <FocusScope contain restoreFocus autoFocus>
        <div
          {...overlayProps}
          {...dialogProps}
          {...modalProps}
          ref={ref}
          style={{
            background: 'white',
            color: 'black',
            padding: 30
          }}
        >
          <h3
            {...titleProps}
            style={{ marginTop: 0 }}
          >
            {title}
          </h3>
          {children}
        </div>
      </FocusScope>
    </div>
  );
}

function Example() {
  let state = useOverlayTriggerState({});

  return (
    <>
      <Button onPress={state.open}>Open Dialog</Button>
      {state.isOpen &&
        (
          <OverlayContainer>
            <ModalDialog
              title="Enter your name"
              isOpen
              onClose={state.close}
              isDismissable
            >
              <form style={{ display: 'flex', flexDirection: 'column' }}>
                <label htmlFor="first-name">First Name:</label>
                <input id="first-name" />
                <label htmlFor="last-name">Last Name:</label>
                <input id="last-name" />
                <Button
                  onPress={state.close}
                  style={{ marginTop: 10 }}
                >
                  Submit
                </Button>
              </form>
            </ModalDialog>
          </OverlayContainer>
        )}
    </>
  );
}

// Application must be wrapped in an OverlayProvider so that it can be
// hidden from screen readers when a modal opens.
<OverlayProvider>
  <Example />
</OverlayProvider>

import {
  FocusScope,
  OverlayContainer,
  OverlayProvider,
  useDialog,
  useModal,
  useOverlay,
  usePreventScroll
} from 'react-aria';

import {useOverlayTriggerState} from 'react-stately';

// Reuse the Button from your component library. See below for details.
import {Button} from 'your-component-library';

function ModalDialog(props) {
  let { title, children } = props;

  // Handle interacting outside the dialog and pressing
  // the Escape key to close the modal.
  let ref = React.useRef();
  let { overlayProps, underlayProps } = useOverlay(
    props,
    ref
  );

  // Prevent scrolling while the modal is open, and hide content
  // outside the modal from screen readers.
  usePreventScroll();
  let { modalProps } = useModal();

  // Get props for the dialog and its title
  let { dialogProps, titleProps } = useDialog(props, ref);

  return (
    <div
      style={{
        position: 'fixed',
        zIndex: 100,
        top: 0,
        left: 0,
        bottom: 0,
        right: 0,
        background: 'rgba(0, 0, 0, 0.5)',
        display: 'flex',
        alignItems: 'center',
        justifyContent: 'center'
      }}
      {...underlayProps}
    >
      <FocusScope contain restoreFocus autoFocus>
        <div
          {...overlayProps}
          {...dialogProps}
          {...modalProps}
          ref={ref}
          style={{
            background: 'white',
            color: 'black',
            padding: 30
          }}
        >
          <h3
            {...titleProps}
            style={{ marginTop: 0 }}
          >
            {title}
          </h3>
          {children}
        </div>
      </FocusScope>
    </div>
  );
}

function Example() {
  let state = useOverlayTriggerState({});

  return (
    <>
      <Button onPress={state.open}>Open Dialog</Button>
      {state.isOpen &&
        (
          <OverlayContainer>
            <ModalDialog
              title="Enter your name"
              isOpen
              onClose={state.close}
              isDismissable
            >
              <form
                style={{
                  display: 'flex',
                  flexDirection: 'column'
                }}
              >
                <label htmlFor="first-name">
                  First Name:
                </label>
                <input id="first-name" />
                <label htmlFor="last-name">
                  Last Name:
                </label>
                <input id="last-name" />
                <Button
                  onPress={state.close}
                  style={{ marginTop: 10 }}
                >
                  Submit
                </Button>
              </form>
            </ModalDialog>
          </OverlayContainer>
        )}
    </>
  );
}

// Application must be wrapped in an OverlayProvider so that it can be
// hidden from screen readers when a modal opens.
<OverlayProvider>
  <Example />
</OverlayProvider>

import {
  FocusScope,
  OverlayContainer,
  OverlayProvider,
  useDialog,
  useModal,
  useOverlay,
  usePreventScroll
} from 'react-aria';

import {useOverlayTriggerState} from 'react-stately';

// Reuse the Button from your component library. See below for details.
import {Button} from 'your-component-library';

function ModalDialog(
  props
) {
  let {
    title,
    children
  } = props;

  // Handle interacting outside the dialog and pressing
  // the Escape key to close the modal.
  let ref = React
    .useRef();
  let {
    overlayProps,
    underlayProps
  } = useOverlay(
    props,
    ref
  );

  // Prevent scrolling while the modal is open, and hide content
  // outside the modal from screen readers.
  usePreventScroll();
  let { modalProps } =
    useModal();

  // Get props for the dialog and its title
  let {
    dialogProps,
    titleProps
  } = useDialog(
    props,
    ref
  );

  return (
    <div
      style={{
        position:
          'fixed',
        zIndex: 100,
        top: 0,
        left: 0,
        bottom: 0,
        right: 0,
        background:
          'rgba(0, 0, 0, 0.5)',
        display: 'flex',
        alignItems:
          'center',
        justifyContent:
          'center'
      }}
      {...underlayProps}
    >
      <FocusScope
        contain
        restoreFocus
        autoFocus
      >
        <div
          {...overlayProps}
          {...dialogProps}
          {...modalProps}
          ref={ref}
          style={{
            background:
              'white',
            color:
              'black',
            padding: 30
          }}
        >
          <h3
            {...titleProps}
            style={{
              marginTop:
                0
            }}
          >
            {title}
          </h3>
          {children}
        </div>
      </FocusScope>
    </div>
  );
}

function Example() {
  let state =
    useOverlayTriggerState(
      {}
    );

  return (
    <>
      <Button
        onPress={state
          .open}
      >
        Open Dialog
      </Button>
      {state.isOpen &&
        (
          <OverlayContainer>
            <ModalDialog
              title="Enter your name"
              isOpen
              onClose={state
                .close}
              isDismissable
            >
              <form
                style={{
                  display:
                    'flex',
                  flexDirection:
                    'column'
                }}
              >
                <label htmlFor="first-name">
                  First
                  Name:
                </label>
                <input id="first-name" />
                <label htmlFor="last-name">
                  Last
                  Name:
                </label>
                <input id="last-name" />
                <Button
                  onPress={state
                    .close}
                  style={{
                    marginTop:
                      10
                  }}
                >
                  Submit
                </Button>
              </form>
            </ModalDialog>
          </OverlayContainer>
        )}
    </>
  );
}

// Application must be wrapped in an OverlayProvider so that it can be
// hidden from screen readers when a modal opens.
<OverlayProvider>
  <Example />
</OverlayProvider>

Button#

The Button component is used in the above example to open and close the dialog. It is built using the useButton hook, and can be shared with many other components.

Show code

import {useButton} from 'react-aria';

function Button(props) {
  let ref = React.useRef();
  let { buttonProps } = useButton(props, ref);
  return (
    <button {...buttonProps} ref={ref} style={props.style}>
      {props.children}
    </button>
  );
}

import {useButton} from 'react-aria';

function Button(props) {
  let ref = React.useRef();
  let { buttonProps } = useButton(props, ref);
  return (
    <button {...buttonProps} ref={ref} style={props.style}>
      {props.children}
    </button>
  );
}

import {useButton} from 'react-aria';

function Button(props) {
  let ref = React
    .useRef();
  let { buttonProps } =
    useButton(
      props,
      ref
    );
  return (
    <button
      {...buttonProps}
      ref={ref}
      style={props.style}
    >
      {props.children}
    </button>
  );
}

Styled examples#

Tailwind CSS

An animated alert dialog using Tailwind and react-transition-group.

Name	Type	Default	Description
`role`	`'dialog' \| 'alertdialog'`	`'dialog'`	The accessibility role for the dialog.
`id`	`string`	—	The element's unique identifier. See MDN.
`aria-label`	`string`	—	Defines a string value that labels the current element.
`aria-labelledby`	`string`	—	Identifies the element (or elements) that labels the current element.
`aria-describedby`	`string`	—	Identifies the element (or elements) that describes the object.
`aria-details`	`string`	—	Identifies the element (or elements) that provide a detailed, extended description for the object.

Name	Type	Description
`dialogProps`	`DOMAttributes`	Props for the dialog container element.
`titleProps`	`DOMAttributes`	Props for the dialog title element.

All DOM attributes supported across both HTML and SVG elements.

Name	Type	Description
`id`	`string \| undefined`
`role`	`AriaRole \| undefined`
`tabIndex`	`number \| undefined`
`style`	`CSSProperties \| undefined`
`className`	`string \| undefined`

Hides content outside the current <OverlayContainer> from screen readers on mount and restores it on unmount. Typically used by modal dialogs and other types of overlays to ensure that only the top-most modal is accessible at once.

useModal(
  (options?: AriaModalOptions
)): ModalAria

Name	Type	Description
`isDisabled`	`boolean`

Name	Type	Description
`modalProps`	`ModalAriaProps`	Props for the modal content element.

Name	Type	Description
`data-ismodal`	`boolean`	Data attribute marks the dom node as a modal for the aria-modal-polyfill.
`id`	`string \| undefined`
`role`	`AriaRole \| undefined`
`tabIndex`	`number \| undefined`
`style`	`CSSProperties \| undefined`
`className`	`string \| undefined`

A FocusScope manages focus for its descendants. It supports containing focus inside the scope, restoring focus to the previously focused element on unmount, and auto focusing children on mount. It also acts as a container for a programmatic focus management interface that can be used to move focus forward and back in response to user events.

Name	Type	Description
`children`	`ReactNode`	The contents of the focus scope.
`contain`	`boolean`	Whether to contain focus inside the scope, so users cannot move focus outside, for example in a modal dialog.
`restoreFocus`	`boolean`	Whether to restore focus back to the element that was focused when the focus scope mounted, after the focus scope unmounts.
`autoFocus`	`boolean`	Whether to auto focus the first focusable element in the focus scope on mount.

Prevents scrolling on the document body on mount, and restores it on unmount. Also ensures that content does not shift due to the scrollbars disappearing.

usePreventScroll(
  (options: PreventScrollOptions
)): any

Name	Type	Description
`isDisabled`	`boolean`	Whether the scroll lock is disabled.

Provides the behavior for overlays such as dialogs, popovers, and menus. Hides the overlay when the user interacts outside it, when the Escape key is pressed, or optionally, on blur. Only the top-most overlay will close at once.

useOverlay(
  (props: AriaOverlayProps,
  , ref: RefObject<Element>
)): OverlayAria

Name	Type	Default	Description
`isOpen`	`boolean`	—	Whether the overlay is currently open.
`onClose`	`() => void`	—	Handler that is called when the overlay should close.
`isDismissable`	`boolean`	`false`	Whether to close the overlay when the user interacts outside it.
`shouldCloseOnBlur`	`boolean`	—	Whether the overlay should close when focus is lost or moves outside it.
`isKeyboardDismissDisabled`	`boolean`	`false`	Whether pressing the escape key to close the overlay should be disabled.
`shouldCloseOnInteractOutside`	`( (element: Element )) => boolean`	—	When user interacts with the argument element outside of the overlay ref, return true if onClose should be called. This gives you a chance to filter out interaction with elements that should not dismiss the overlay. By default, onClose will always be called on interaction outside the overlay ref.

Name	Type	Description
`overlayProps`	`DOMAttributes`	Props to apply to the overlay container element.
`underlayProps`	`DOMAttributes`	Props to apply to the underlay element, if any.

An OverlayProvider acts as a container for the top-level application. Any application that uses modal dialogs or other overlays should be wrapped in a <OverlayProvider>. This is used to ensure that the main content of the application is hidden from screen readers if a modal or other overlay is opened. Only the top-most modal or overlay should be accessible at once.

Name	Type	Description
`children`	`ReactNode`
`id`	`string \| undefined`
`role`	`AriaRole \| undefined`
`tabIndex`	`number \| undefined`
`style`	`CSSProperties \| undefined`
`className`	`string \| undefined`

A container for overlays like modals and popovers. Renders the overlay into a Portal which is placed at the end of the document body. Also ensures that the overlay is hidden from screen readers if a nested modal is opened. Only the top-most modal or overlay should be accessible at once.

Name	Type	Default	Description
`children`	`ReactNode`	—
`portalContainer`	`Element`	`document.body`	The container element in which the overlay portal will be placed.
`id`	`string \| undefined`	—
`role`	`AriaRole \| undefined`	—
`tabIndex`	`number \| undefined`	—
`style`	`CSSProperties \| undefined`	—
`className`	`string \| undefined`	—