CMS Design System

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.

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

`<Dialog />`

View Source File

Open in Storybook

Code snippet

Props

React Properties Documentation
Name	Type	Default	Description
`alert`	`boolean`		If true, the modal will receive a role of alertdialog, instead of its default dialog.
`children`	`React.ReactNode`
`mounted`	`boolean \| 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.
`applicationNode`	`Node \| 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.
`includeDefaultStyles`	`boolean \| 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.
`dialogClass`	`string \| 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`.
`dialogId`	`string \| undefined`		Choose your own id attribute for the dialog element. Default: `react-aria-modal-dialog`.
`dialogStyle`	`React.CSSProperties \| undefined`		Customize properties of the style prop that is passed to the dialog.
`focusDialog`	`boolean \| 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.)
`initialFocus`	`string \| 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.)
`titleText`	`string \| 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.
`titleId`	`string \| 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.
`underlayStyle`	`React.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.
`underlayClass`	`string \| 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`.
`underlayClickExits`	`boolean \| undefined`	`false`	By default, a click on the underlay will exit the modal. Pass `false`, and clicking on the underlay will do nothing.
`escapeExits`	`boolean \| undefined`	`true`	By default, the Escape key exits the modal. Pass `false`, and it won't.
`underlayColor`	`string \| 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)
`verticallyCenter`	`boolean \| undefined`		If `true`, the modal's contents will be vertically (as well as horizontally) centered.
`focusTrapPaused`	`boolean \| 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 hierachical traps is handled automatically.
`focusTrapOptions`	`Record<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.
`scrollDisabled`	`boolean \| undefined`		If true, the modal dialog will prevent any scrolling behind the modal window.
`analytics`	`boolean`		Analytics events tracking is enabled by default. Set this value to `false` to disable tracking for this component instance.
`analyticsLabelOverride`	`string`		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.
`actions`	`React.ReactNode`		Buttons or other HTML to be rendered in the "actions" bar at the bottom of the dialog.
`actionsClassName`	`string`		Additional classes to be added to the actions container.
`ariaCloseLabel`	`string`		Aria label for the close button
`className`	`string`		Additional classes to be added to the root dialog element.
`closeButtonSize`	`'small' \| 'big'`		Size of the close button. See Button component
`closeButtonText`	`React.ReactNode`		For internationalization purposes, the text for the "Close" button must be passed in as a prop.
`closeButtonVariation`	`ButtonVariation`	`'transparent'`	Variation string to be applied to close button component. See Button component
`closeIcon`	`React.ReactNode`	`<CloseIcon />`	The icon to display as part of the close button
`headerClassName`	`string`		Additional classes to be added to the header, which wraps the heading and close button.
`heading`	`React.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_props`	`AriaModalProps`		Allow additional AriaModal props to be passed to Dialog

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

Customization

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

Variable	Default Core Theme Value
`$dialog__background-color`	`$color-white`
`$dialog__padding`	`32px`
`$dialog-overlay__background-color`	`$color-background-dialog-mask`

Alert

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.