Storybook
SketchExamples
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
| Name | Type | Default | Description |
|---|---|---|---|
actions | 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. | |
alert | boolean | If true, the modal will receive a role of alertdialog, instead of its
default dialog. The alertdialog role should only be used when an
alert, error, or warning occurs. | |
ariaCloseLabel | string | Aria label for the close button | |
backdropClickExits | boolean | Pass true to have the dialog close when its backdrop pseudo-element is clicked | |
className | string | Additional classes to be added to the root dialog element. | |
closeButtonSize | DialogCloseButtonSize | Size of the close button. See Button component | |
closeButtonText | ReactNode | For internationalization purposes, the text for the "Close" button must be passed in as a prop. | |
closeButtonVariation | ButtonVariation | ghost | Variation string to be applied to close button component. See Button component |
closeIcon | 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 | ReactNode | The Dialog's heading, to be rendered in the header alongside the close button. | |
id | string | A custom id attribute for the dialog element | |
onEnter | () => void | This function is called after the modal opens | |
onExitrequired | (event: MouseEvent<Element, MouseEvent> | KeyboardEvent<Element>) => void | This function needs to handles the state change of exiting (or deactivating) the modal.
Maybe it's just a wrapper around setState(); or maybe you use some more involved
Flux-inspired state management — whatever the case, this module leaves the state
management up to you instead of making assumptions.
That also makes it easier to create your own "close modal" buttons; because you
have the function that closes the modal right there, written by you, at your disposal. | |
size | DialogSize | The Dialog's size parameter. | |
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. | |
analyticsEventTypeOverride | string | If you need the event_type to be overridden for your use case, you can provide
an alternate string here. Suggested values can be found in the EventType enum. | |
onAnalyticsEvent | (event: AnalyticsEvent) => void | Optional callback that will intercept analytics events for this component.
If none is specified, the design system will use the default analytics
function, which can be overwritten globally with setDefaultAnalyticsFunction. |
Styles
The following CSS variables can be overridden to customize Dialog components:
Analytics
This component has analytics tracking available. Please see our developer documentation about using analytics in the design system.
Guidance
Accessibility
Keyboard support
EnterorSpaceto select the highlighted item.Tabto move the focus sequentially through the list of focusable items.Shift + Tabto 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
escapeExitsprop tofalse - 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
initialFocusprop with boolean propfocusDialogset tofalse
Learn more
- Making an accessible dialog box
- GOV.UK modal dialog boxes discussion
- Overuse of Overlays: How to Avoid Misusing Lightboxes
- Using ARIA role=dialog to implement a modal dialog box
Related patterns
Component maturity
For more information about how we tested and validated our work for each checklist item, read our component maturity documentation.