Dialog

Dialog is a window that opens over the application content, focusing the user’s attention on a particular task or piece of information. It communicates new information, errors, warnings or successful completion of a process.

Also known as: Modal, Modal dialog, Overlay, Popup
Salt package@salt-ds/core
Available since1.20.0
Code
Note: This tab list includes overflow; tab positions may be inaccurate or change when a tab is selected

Best practices

Accessible name

Provide an accessible name for dialogs by using the visible DialogHeader (recommended) or, if design constraints prevent this, apply an aria-label attribute directly to the Dialog to meet WCAG 4.1.2 requirements.

Focus

The dialog component will trap focus within the dialog when open. This means that the user will not be able to tab out of the dialog and focus will be set to the first focusable element within the dialog. When the dialog is closed, focus will return to the element that triggered the dialog.

Initial focus

You can control which element receives focus when the dialog is opened by passing an initialFocus prop to the dialog component. This prop accepts a number, which indicates the index of the tabbable element within the dialog that should receive focus. If no element is found, focus will be set to the first focusable element within the Dialog. The initialFocus can also be a ref to an element within the dialog.

Focus sequence

  • For dialogs that prompt for user confirmation, the call to action button takes focus first.
  • For dialogs with destructive interactions, the cancel button takes focus first.

Scrollable content

When content in the dialog is scrollable, it will receive keyboard focus (with a visible focus indicator). This allows keyboard and screen reader reliant users to navigate and scroll the content using arrow keys, satisfying WCAG 2.1.1 and related accessibility requirements.

Keyboard interactions

KeyFunction
Tab
  • If focus is in the dialog, Tab sets focus to the next focusable component in the tab order.
  • If the last element in the dialog has focus, Tab wraps to the first focusable element in the dialog.
Shift + Tab
  • If focus is in the dialog, this action sets focus to the previous focusable component in the tab order.
  • If the first element in the dialog has focus, this action wraps to the last focusable element in the dialog.
Escape
  • If focus is in the dialog, Escape closes the dialog and returns focus to the triggering element.
Enter / Space
  • If focus is on a button in the dialog button bar, this action activates the button.
  • If focus is on the close button, this action activates the close button, closes the dialog and returns focus to the triggering element.