BRAID
Braid Logo
 

Dialog

A modal overlay that focusses user attention by disabling the screen to show a message.
Open in Playroom

Accessibility

Follows the WAI-ARIA Dialog (Modal) Pattern.Due to the size of the Dialog, all entrance and exit animations adhere to the users reduce motion preference.

Title and description

The title prop provides an accessible name announced to the user when the Dialog is opened. Optionally, a description can be provided and will be announced by a screen reader as well as visually forming part of the header block.
Open in Playroom

Width

The width prop can be set to xsmall, small, medium or large for standardised widths, or content to take on the width of it’s contents.
Select width:
xsmall
Open in Playroom

Cover images

You can provide a URL for a cover image to display at the top of the Dialog via the coverImage prop. The provided image must be compatible with the CSS background-image “url” function.For best results, the image should be 16:9 aspect ratio with a 1:1 safe area in the centre. To prevent over-cropping the image in this layout, the Dialog is restricted to a maximum height of 60vh.Additionally, in this layout the content on the left is scrollable, while the cover image remains fixed.
Open in Playroom
On mobile, the coverImage will be stacked vertically above the content. In this layout the cover image will be scrolled with the content.
Open in Playroom

Illustrations

You can provide an element to display at the top of the Dialog via the illustration prop.
Open in Playroom

Tailoring the close behaviour

The onClose function is called when the user either click the close button inside the Dialog, or clicks on the backdrop outside the Dialog.Translation hint The aria-label for the close button can be tailored by providing a closeLabel prop.
Open in Playroom
To prevent the Dialog from closing, e.g. due to validation, this function should return false.
Open in Playroom

Scrollable dialogs

If the contents are unable to fit on the screen, Dialogs become scrollable with a fixed close button.If you need to display a large amount of content, consider using a Drawer instead.
Open in Playroom

Nested dialogs

Although supported, in order to keep experiences simple nesting Dialogs is not encouraged.
Open in Playroom

General best practice

  • A Dialog can be triggered on any element of your choice, but should always be directly connected to a user action such as clicking a button.
  • Avoid displaying a Dialog on page load, as users tend to dismiss these without reading them.

When to use

Use a Dialog:
  • to reveal secondary information including images or interactive elements
  • to confirm an important user action (e.g. deleting a piece of data).
Don’t use a Dialog:
  • if your content is less than 20 words in length (consider using a TooltipRenderer instead)
  • to capture complex user input, such as in a form (consider using a Drawer instead).

Development considerations

It’s recommended that you connect the Dialog’s open state to your router so that it can be closed via the browser’s back button.

Data attributes

Braid components are very explicit about the properties they accept, which makes providing arbitrary data attributes not possible. Instead, a data prop can be provided as a single collection of data attributes.
<Dialog
  data={{ testid: 'dialog-1' }}
  // => data-testid="dialog-1"
>
  ...
</Dialog>
Open in Playroom

Alternatives

  • Drawer — For exposing complex content or capturing user input in a modal panel.
  • Accordion — For revealing sections of content in a vertically stacked list.
  • Disclosure — For revealing optional content inline with a light visual treatment.
On this page