Usage guidance
Due to their inherently disruptive nature, Dialogs
should be used sparingly on a page and saved for situations where it's required for the user to acknowledge or review an action or situation before returning to the active task. The content of a Dialog
should be both clear and concise.
A Dialog
will block further interactions with the page (including scrolling) until it is closed. This can happen by the user clicking the included close button, or performing one of the actions within the footer.
An optional decorative header can be provided, by specifying mode="decorative"
on the Dialog.Header
. Additionally, a variant
can also be specified (in the same manner as Notification) to change the decorative header styling. This will change the icon present as well, but a custom icon can be provided via customIconOverride
too.
A close button is provided by the Dialog
and whilst it should always be visible, it can be overridden via the closeButtonOverride
prop.
The Dialog
can also be center aligned using alignCenter
.
Dialog
is available in two different sizes: medium
and large
. In most cases, the default value should be used. When using size="large"
you must also set the size for the non-namespaced child components, such as Paragraph.
Accessibility
Dialog
must have a Dialog.Header
child component provided in order to meet modal accessibility requirements via aria-describedby
.
It is recommended to have the initial focus set on the most relevant element—in most cases the confirmation button. To do so, pass the autoFocus
prop to a Dialog.Button
subcomponent used in the Dialog.Footer
.
If no initial focus is explicitly set, then the close button will be focused by default.
Best practices
Examples
Basic usage
Sizes
Center aligned
Decorative header
Decorative header with custom icon
Custom close
Playground
Props
Dialog
In addition to the props listed below, Dialog
accepts all props from React.HTMLAttributes<HTMLDivElement>
, except: role
.
Name | Type | Description |
---|---|---|
alignCenter | boolean | Whether to center align the Dialog content and buttons. Default:
|
aria-label | string | Accessible label for the Dialog, where |
children Required | React.ReactNode | Content of the Dialog. In general, Dialog's own subcomponents should be used: |
closeButtonOverride | JSX.Element | Custom close button component. In general use |
isOpen Required | boolean | Determines if the Dialog is open. |
onClose Required | ()
=> void | Handler called when the Dialog will close. |
size | large medium | Defines the size of the Dialog. In most cases, the default size should be used. Default:
|
Dialog.Body
In addition to the props listed below, Dialog.Body
accepts all props from React.HTMLAttributes<HTMLDivElement>
.
Name | Type | Description |
---|---|---|
children Required | React.ReactNode | Dialog main content or description. When it is getting long, subtle scroll indicators appear at the top and bottom. |
Dialog.Button
In addition to the props listed below, Dialog.Button
accepts all props from Waffles Button, except: fullWidth
, icon
.
Name | Type | Description |
---|---|---|
autoFocus | boolean | Focus this particular Button when the modal parent is opened. Default:
|
Dialog.CloseButton
In addition to the props listed below, Dialog.CloseButton
accepts all props from React.HTMLAttributes<HTMLButtonElement>
, except: children
.
Name | Type | Description |
---|---|---|
aria-label | string | Optional override for the close button accessible label. Default:
|
Dialog.Footer
In addition to the props listed below, Dialog.Footer
accepts all props from React.HTMLAttributes<HTMLDivElement>
.
Name | Type | Description |
---|---|---|
children Required | React.ReactNode | Content of the footer. In most cases, should be one or multiple |
Dialog.Header
In addition to the props listed below, Dialog.Header
accepts all props from Waffles Heading, except: inverted
.
Name | Type | Description |
---|---|---|
customIconOverride | JSX.Element | Custom icon override for the decorative header, only applicable when |
mode | decorative plain | Mode of the Dialog header, determining if the Dialog has a decorative banner at the top. Default:
|
variant | error info success upgrade warning | Variant of the header, only applicable when Default:
|
Imports
You can import the following components, utilities or types from this module:
import { Dialog, useHasParentDialog } from '@datacamp/waffles/dialog';import type {DialogProps,BodyProps,ButtonProps,CloseButtonProps,FooterProps,HeaderProps,} from '@datacamp/waffles/dialog';