Waffles - Dialog

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

import { useState } from 'react';
import { Dialog } from '@datacamp/waffles/dialog';
import { Button } from '@datacamp/waffles/button';

function Playground() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open Dialog</Button>
      <Dialog
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      >
        <Dialog.Header>
          Dialog title
        </Dialog.Header>
        <Dialog.Body>
          Main content of the dialog. Even very long content is supported.
        </Dialog.Body>
        <Dialog.Footer>
          <Dialog.Button onClick={() => setIsOpen(false)}>
            Cancel
          </Dialog.Button>
          <Dialog.Button
            onClick={() => setIsOpen(false)}
          >
            Secondary Action
          </Dialog.Button>
          <Dialog.Button
            autoFocus
            variant="primary"
            onClick={() => setIsOpen(false)}
          >
            Confirm
          </Dialog.Button>
        </Dialog.Footer>
      </Dialog>
    </>
  );
}

import { useState } from 'react';
import { Dialog } from '@datacamp/waffles/dialog';
import { Button } from '@datacamp/waffles/button';

function Playground() {
  const [isOpen, setIsOpen] = useState(false);

  return (
    <>
      <Button onClick={() => setIsOpen(true)}>Open Dialog</Button>
      <Dialog
        isOpen={isOpen}
        onClose={() => setIsOpen(false)}
      >
        <Dialog.Header>
          Dialog title
        </Dialog.Header>
        <Dialog.Body>
          Main content of the dialog. Even very long content is supported.
        </Dialog.Body>
        <Dialog.Footer>
          <Dialog.Button onClick={() => setIsOpen(false)}>
            Cancel
          </Dialog.Button>
          <Dialog.Button
            onClick={() => setIsOpen(false)}
          >
            Secondary Action
          </Dialog.Button>
          <Dialog.Button
            autoFocus
            variant="primary"
            onClick={() => setIsOpen(false)}
          >
            Confirm
          </Dialog.Button>
        </Dialog.Footer>
      </Dialog>
    </>
  );
}

Live

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: `false`
`aria-label`	`string`	Accessible label for the Dialog, where `Dialog.Body` does not contain descriptive content (e.g. form elements).
`children`Required	`React.ReactNode`	Content of the Dialog. In general, Dialog's own subcomponents should be used: `Dialog.Header`, `Dialog.Body`, and `Dialog.Footer`.
`closeButtonOverride`	`JSX.Element`	Custom close button component. In general use `Dialog.CloseButton` subcomponent.
`isOpen`Required	`boolean`	Determines if the Dialog is open.
`onClose`Required	`() => void`	Handler called when the Dialog will close.
`size`	`largemedium`	Defines the size of the Dialog. In most cases, the default size should be used. Default: `medium`

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: `false`

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: `Close`

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.Button` subcomponents.

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"`. In general, use Waffles Icon.
`mode`	`decorativeplain`	Mode of the Dialog header, determining if the Dialog has a decorative banner at the top. Default: `plain`
`variant`	`errorinfosuccessupgradewarning`	Variant of the header, only applicable when `mode="decorative"`. Default: `info`

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';