mui / mui/base-ui

[dialog][docs] Document the difference(s) between `Dialog` and `AlertDialog`

Open
#1,687 1 comment 1 reaction 0 assignees View on GitHub
component: alert dialog component: dialog docs
Dominant language
TypeScript
Stars
10.9k
Forks
543
Avg merge
1d 20h
Merged PRs (30d)
101

Description

# Docs feedback

## How can we improve Base UI documentation?

As I implement my own styled modal dialog component with Base UI, I am wondering when to use `Dialog` and when to use `AlertDialog`. I've read the MDN pages for the [dialog](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/dialog_role) and [alertdialog](https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Reference/Roles/alertdialog_role) roles, but I feel like the Base UI docs should have a section about the actual differences in behavior, as implemented in Base UI. Otherwise, the user is left comparing both pages and noticing that, for example, `Dialog.Root` has `dismissible` and `modal` props while `AlertDialog.Root` doesn't (why? I guess because alert dialogs are always modal and never dismissible, but perhaps that should be said) and that `AlertDialog` doesn't seem to have the same support for nested dialogs (or maybe the documentation of that feature is just less complete on the `AlertDialog` page?).

If the only difference is the default value of `(Alert)Dialog.Popup`'s `role` attribute and the absence of some props in `AlertDialog` because it doesn't support dismissibility or non-modality for accessibility reasons, I wonder if it's acceptable, for my reusable styled dialog component, to always use Base UI's `Dialog` and accept a `role` prop which, when set to `alertdialog`, would set `Dialog.Root`'s `dismissible` prop to `false` and override `Dialog.Popup`'s `role`? It feels cleaner than conditionally rendering `Dialog` or `AlertDialog` parts everywhere.

Thank you!

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.