Dialog

A modal dialog: it blocks progress until it is answered. It is a native <dialog> opened with showModal(): it moves focus inside on opening, keeps it there while open, makes the rest of the page inert and returns focus to the trigger on closing.

When to use it

• A decision that cannot be ignored, or a short form that makes sense without leaving the screen.
• kind="alert" for destructive confirmations: it is announced as alertdialog and does not close when clicking outside, so a stray click does not answer on anyone's behalf. Escape does close it, as a cancellation (the WAI-ARIA alertdialog pattern).
• With trigger it opens and closes on its own; without it, whoever uses it drives it with open and onOpenChange.
• actions receives close, so the action button closes it without keeping the state outside; footerStart puts something on the left of the footer.
• loading while its content is arriving: the body has aria-busy and says loadingText ("Loading…").
• dismissable={false} for a half-filled form that must not be lost by a click outside.

When not to

• An "are you sure?" attached to the button: ConfirmAction. If the question is asked from code, useConfirmation.
• Filters or the detail of a row, which slide in from a side: Drawer.
• A panel attached to its button, without a backdrop: Dropdown.
• If it needs a lot of scrolling, it is probably a page.

Keyboard: on opening, focus enters; Tab and Shift+Tab stay inside. Escape closes and focus returns to the trigger; in kind="alert" it counts as cancel and reaches onOpenChange(false). Clicking outside closes only the regular one.

Accessibility: it is announced as dialog (or alertdialog) with the title as its name, and description as its accessible description. The X appears with withCloseButton, never on alert dialogs, and is named with closeLabel ("Close the dialog"). The icon of the tone is decoration: the title has to say everything. onClosed arrives when the dialog has already gone (after the exit animation) and focus has already returned: it is the place to move focus elsewhere or to announce something.

Fine-tuning: CSS variables --amset-dialog-*: -width, -padding, -radius, -background and -slot; the backdrop, --amset-overlay-background and --amset-overlay-padding. What is stacked comes from the --amset-layer-* scale (modal is 100).

Custom header: icon (with the color of accent) in place of the tone's, headerActions between the title and the X, and title can be a node. width gives a custom width (a number is pixels, a string is a CSS measure) and takes precedence over size; placement="top" pins it to the top, for what grows downward like a palette; hideHeader hides the header without losing the accessible name; flush removes the body padding and bodyColumn makes it a flex column, for content with its own scrolling.

Embedded: with inline the same box is rendered IN the page, as a region with its title: no <dialog>, no backdrop, no Escape and no focus trap, and no X. It is useful for reusing as a screen panel what is a dialog on another. open shows or hides it.

What scrolls is the body: the header and the footer stay still, and the lines that separate them appear only if the body does not fit entirely. With the whole dialog scrolling, in a long one the title went off the screen (measured: −563 px after scrolling 600) and the buttons only appeared on reaching the end.