Dialog

The Dialog component has been designed with accessibility in mind, providing features that enhance the experience for users of assistive technologies.

The following props are available to improve the accessibility of your Dialog component:

The Dialog component automatically implements the following accessibility features:

• role="dialog": Identifies the element as a dialog to assistive technologies.

• aria-modal="true": Indicates that the dialog is modal, meaning it blocks interaction with page content.

• aria-labelledby: Automatically associates the dialog with its title for screen readers using a generated ID.

• aria-describedby: When a description is provided, it’s automatically associated with the dialog using a generated ID.

• The Dialog’s animations respect the user’s reduced motion preferences.

• When opened, focus is automatically moved to the first focusable element within the dialog.

• When closed, focus returns to the element that triggered the dialog (when triggerRef is provided).

• Always provide a descriptive title that clearly indicates the purpose of the dialog.

• Use the description prop to provide additional context when needed, especially for complex interactions.

• Ensure that primary and secondary actions have clear, descriptive labels that indicate their purpose.

• Use semantic heading levels (titleAs prop) that fit within your page’s heading hierarchy. For example, if your dialog appears within a page section that uses h2, consider using titleAs="h3" for proper document structure.

• Test keyboard navigation within the dialog to ensure all interactive elements are accessible.

• When creating a dialog trigger, help screen reader users understand the relationship between the trigger and the dialog:

  1. Apply aria-expanded="true" to the trigger element when the dialog is open and aria-expanded="false" when it’s closed.
  2. Use aria-controls on the trigger element to associate it with the dialog via Dialog component’s id.

The Dialog component supports the following keyboard interactions:

• Escape key closes the dialog
• Tab key navigates through focusable elements within the dialog, with focus being contained within the dialog while it’s open
• Enter/Space keys activate buttons and other interactive elements within the dialog

<Dialog
  title="Edit your profile information"
  titleAs="h2"
  description="Update your personal details to keep your account information current."
  primaryAction={<Button type="critical">Save changes</Button>}
  secondaryAction={<Button type="secondary">Cancel</Button>}
  onClose={() => handleClose()}
/>

function ExampleComponent() {
  const [isOpen, setIsOpen] = React.useState(false);
  const buttonRef = React.useRef(null);
  return (
    <>
      <Button ref={buttonRef} onClick={() => setIsOpen(true)} aria-expanded={isOpen}>
        Change email preferences
      </Button>
      {isOpen && (
        <Dialog
          title="Email notification settings"
          description="Choose which email notifications you'd like to receive from us."
          primaryAction={
            <Button
              onClick={() => {
                savePreferences();
                setIsOpen(false);
              }}
            >
              Save preferences
            </Button>
          }
          secondaryAction={
            <Button type="secondary" onClick={() => setIsOpen(false)}>
              Cancel
            </Button>
          }
          onClose={() => setIsOpen(false)}
          triggerRef={buttonRef}
        />
      )}
    </>
  );
}