Skip to main content
U.S. Flag

An official website of the United States government

Modal Dialog

The dialog component can be used to focus a user's attention on a single piece of content, without taking them to a new screen. Please use with caution; view our guidance for more details.

Examples

Loading

Dialog size variants

Apply one of the size modifier classes to the ds-c-dialog element to change the dialog width.

  • .ds-c-dialog--narrow
  • .ds-c-dialog--wide
  • .ds-c-dialog--full

Code

React

React Properties Documentation
NameTypeDefaultDescription
alertboolean

If true, the modal will receive a role of alertdialog, instead of its default dialog.

childrenReact.ReactNode
mountedboolean | undefined

By default, the modal is active when mounted, deactivated when unmounted. However, you can also control its active/inactive state by changing its mounted property instead.

applicationNodeNode | Element | undefined

Provide your main application node here (which the modal should render outside of), and when the modal is open this application node will receive the attribute aria-hidden="true". This can help screen readers understand what's going on.

includeDefaultStylesboolean | undefined

By default, styles are applied inline to the dialog and underlay portions of the component. However, you can disable all inline styles by setting includeDefaultStyles to false. If set, you must specify all styles externally, including positioning. This is helpful if your project uses external CSS assets.

Note: underlayStyle and dialogStyle can still be set inline, but these will be the only styles applied.

dialogClassstring | undefined

Apply a class to the dialog in order to custom-style it.

Be aware that, by default, this module does apply various inline styles to the dialog element in order position it. To disable all inline styles, see includeDefaultStyles.

dialogIdstring | undefined

Choose your own id attribute for the dialog element.

Default: react-aria-modal-dialog.

dialogStyleReact.CSSProperties | undefined

Customize properties of the style prop that is passed to the dialog.

focusDialogboolean | undefined

By default, when the modal activates its first focusable child will receive focus. However, if focusDialog is true, the dialog itself will receive initial focus — and that focus will be hidden. (This is essentially what Bootstrap does with their modal.)

initialFocusstring | undefined

By default, when the modal activates its first focusable child will receive focus. If, instead, you want to identify a specific element that should receive initial focus, pass a selector string to this prop. (That selector is passed to document.querySelector() to find the DOM node.)

titleTextstring | undefined

A string to use as the modal's accessible title. This value is passed to the modal's aria-label attribute. You must use either titleId or titleText, but not both.

titleIdstring | undefined

The id of the element that should be used as the modal's accessible title. This value is passed to the modal's aria-labelledby attribute. You must use either titleId or titleText, but not both.

underlayStyleReact.CSSProperties | undefined

Customize properties of the style prop that is passed to the underlay. The best way to add some vertical displacement to the dialog is to add top & bottom padding to the underlay. This is illustrated in the demo examples.

underlayClassstring | undefined

Apply a class to the underlay in order to custom-style it. This module does apply various inline styles, though, so be aware that overriding some styles might be difficult. If, for example, you want to change the underlay's color, you should probably use the underlayColor prop instead of a class. If you would rather control all CSS, see includeDefaultStyles.

underlayClickExitsboolean | undefinedfalse

By default, a click on the underlay will exit the modal. Pass false, and clicking on the underlay will do nothing.

escapeExitsboolean | undefinedtrue

By default, the Escape key exits the modal. Pass false, and it won't.

underlayColorstring | false | undefined

If you want to change the underlay's color, you can do that with this prop. If false, no background color will be applied with inline styles. Presumably you will apply then yourself via an underlayClass.

Default: rgba(0,0,0,0.5)

verticallyCenterboolean | undefined

If true, the modal's contents will be vertically (as well as horizontally) centered.

focusTrapPausedboolean | undefined

If true, the modal dialog's focus trap will be paused. You won't typically need to use this prop. It used to be that the typical reason for pausing a focus trap was to enable nested focus traps; but as of focus-trap v4, the pausing and unpausing of hierarchical traps is handled automatically.

focusTrapOptionsRecord<string, unknown> | undefined

Customize properties of the focusTrapOptions prop that is passed to the modal dialog's focus trap. For example, you can use this prop if you need better control of where focus is returned.

scrollDisabledboolean | undefined

If true, the modal dialog will prevent any scrolling behind the modal window.

analyticsboolean

Analytics events tracking is enabled by default. Set this value to false to disable tracking for this component instance.

analyticsLabelOverridestring

An override for the dynamic content sent to analytics services. By default this content comes from the heading.

In cases where this component’s heading may contain sensitive information, use this prop to override what is sent to analytics.

actionsReact.ReactNode

Buttons or other HTML to be rendered in the "actions" bar at the bottom of the dialog.

actionsClassNamestring

Additional classes to be added to the actions container.

ariaCloseLabelstring

Aria label for the close button

classNamestring

Additional classes to be added to the root dialog element.

closeButtonSize'small' | 'big'

Size of the close button. See Button component

closeButtonTextReact.ReactNode

For internationalization purposes, the text for the "Close" button must be passed in as a prop.

closeButtonVariationButtonVariation'ghost'

Variation string to be applied to close button component. See Button component

closeIconReact.ReactNode<CloseIcon />

The icon to display as part of the close button

headerClassNamestring

Additional classes to be added to the header, which wraps the heading and close button.

headingReact.ReactNode

The Dialog's heading, to be rendered in the header alongside the close button.

size'narrow' | 'wide' | 'full'

The Dialog's size parameter.

additional_propsAriaModalProps

Allow additional AriaModal props to be passed to Dialog

escapeExitDisabledfalse

Styles

The following Sass variables can be overridden to customize Dialog components:

Sass variables for dialog
VariableDefault Core Theme Value
$dialog__background-color$color-white
$dialog__padding32px
$dialog-overlay__background-color$color-transparent-black-alpha50

Google Analytics

Analytics event tracking is disabled by default.

Enable event tracking

Import and set the setDialogSendsAnalytics feature flag to true in your application's entry file:

import { setDialogSendsAnalytics } from '@cmsgov/<design-system-package>';
setDialogSendsAnalytics(true);

On applications where the page has utag loaded, the data goes to Tealium which allows it to route to Google Analytics or the currently approved data analytics tools.

Disable event tracking

For the analytics prop, pass the value false to the component to disable analytics tracking for a singular component instance

analytics={false}

Override event tracking

A custom heading value can be sent for an analytics event by using the prop analyticsLabelOverride. It is recommended that this value be used to prevent sensitive personal information from being passed to analytics trackers.

Guidance

Usage

  • <Dialog> makes use of the <AriaModal> component maintained by react-aria-modal docs on Github. The above documented props are only those directly exposed by the <Dialog> component, but you can pass props specific to <AriaModal> here as well, e.g. you can set the scrollDisabled prop if you'd like to enable scrolling behind the modal window.

Accessibility

Keyboard support

  • Enter or Space to select the highlighted item.
  • Tab to move the focus sequentially through the list of focusable items.
  • Shift + Tab to move the focus sequentially through the list of focusable items in reversed order.

Focus Management

  • When the modal is opened, the entire modal is the default focus state. Most screen readers will announce the entire dialog content.
  • Focus is trapped within the modal and users can then navigate through the dialog actions with the keyboard.
  • Escape will close the modal. To disable exiting when users press the Escape key, set the escapeExits prop to false
  • When the modal closes, focus returns to the element that was focused just before the modal is activated
  • To place the focus inside of the dialog on activating the modal, set the dialog focus using the initialFocus prop with boolean prop focusDialog set to false

Learn more