Dialog

Stable

A modal window on the native dialog element, with a title, a body that scrolls and a footer for buttons.

Also known as modal, modal dialog, popup window, alert dialog

Install with npm install @tattva/ui (setup), or copy the code from the kit in Downloads.

function Example() {
  const [open, setOpen] = useState(false);
  return (
    <>
      <Button variant="secondary" onClick={() => setOpen(true)}>Publish changes</Button>
      <Dialog open={open} onClose={() => setOpen(false)} title="Publish these changes?" description="People with the link will see the new version right away."
        footer={<>
          <Button variant="secondary" onClick={() => setOpen(false)}>Cancel</Button>
          <Button onClick={() => setOpen(false)}>Publish</Button>
        </>}>
        <p>You can go back to the earlier version from the history list.</p>
      </Dialog>
    </>
  );
}

The simplest use: a title, a line of context and two buttons. The main action goes last.

Usage Code Design Accessibility

When to use it

Stops the person to ask for a decision or a small amount of input that must be settled before they go on. Everything behind it is locked until it closes.

Made of: Backdrop · Panel · Danger label (destructive only) · Title · Description · Close button · Body · Footer

Use it for

Confirming an action that is hard to undo, such as deleting a project.
A short form that must be finished before moving on.
Long content that should stay out of the page until asked for, such as terms.

Not for

A message that does not need an answer: use Toast.
A note that stays on the page: use Callout.
A short list of choices next to a button: use Popover.
A menu of actions for one item: use ToolMenu.

Do and avoid

Delete this trip?

Your bookings stay, but the plan is gone.

Do. Stops people only for a choice they must make now.

Saved

Your trip was saved.

Avoid. A pop-up for news with nothing to decide just blocks the way.

Do

Keep the open value in your own code and set it to false in onClose.
Name the footer buttons after what they do.
Put one clear main action in the footer and make the way out equally easy to find.
Keep the body short. If it needs a full page, make it a page.
Use tone destructive for actions that cannot be undone.

Avoid

Do not open a Dialog for a message that needs no answer. Use a Toast or a Callout.
Do not stack one Dialog on top of another.
Do not use it for a short list of choices. Use a Popover or a menu.
Do not set dismissible to false unless leaving without choosing would cause harm.
Do not rely on the red tone alone to warn. The label and your wording must say it too.

On a phone

On a phone the dialog opens from the bottom as a sheet with rounded top corners; from 640px it is centered.
It is at most 90% of the screen height, the body scrolls inside, and scrolling does not pass through to the page.
The footer buttons stack in a column on a phone, sit side by side from 640px, and stay clear of the bottom safe area.
Tapping the backdrop closes it unless you made it not dismissible.

Properties

Prop	Type	Default	Description
openrequired	boolean	none	Whether the dialog is showing. Your code owns it.
onCloserequired	() => void	none	Called when the person asks to close: Escape, a click on the backdrop or the Close button. Set open to false in response.
titlerequired	string	none	Rendered as the h2 heading and used as the dialog's name through aria-labelledby.
description	string	none	Shown under the title and linked with aria-describedby.
children	ReactNode	none	The body. It scrolls when it is too tall.
footer	ReactNode	none	Usually buttons. They sit in a bar under the body, stacked on phones and in a row from the sm breakpoint.
size	"sm" \| "md" \| "lg"	"md"	Maximum width from the sm breakpoint up: 24rem, 32rem or 42rem. On phones it is always full width.
dismissible	boolean	true	When false, Escape and backdrop clicks do nothing and the Close button is hidden. Only your footer buttons can close it.
tone	"default" \| "destructive"	"default"	Destructive adds a danger icon and the word Destructive above the title, and sets role="alertdialog".
className	string	none	Classes added to the panel.

"Show code under the preview gives the code for the example on the stage."

States

States this part has beyond its default look. Build each one your screen can reach. States set by a property are in the Code tab.

closed: With open false nothing is drawn and the page behaves as normal.
open: The page behind is inert, cannot scroll, and focus moves into the window. Focus returns to the opener once it has gone.
closing: After open turns false the panel fades out in --dur-fast and cannot be pressed. It stays modal until it has gone. Under reduced motion it goes at once.
scrolling body: When the body is taller than the window, only the body scrolls and the title and footer stay in view.
bottom sheet: Under the sm breakpoint the panel is full width with rounded top corners and sits at the bottom of the screen.
focus: A visible focus ring shows on the Close button, on footer buttons and on controls in the body when reached by keyboard.

Tokens

Change one of these and every part that uses it follows.

--surface-raised
--border
--scrim
--shadow-lg
--danger-fg
--fg
--fg-muted
--dur-fast
--dur-base
--dur-slow
--focus-ring
--radius-overlay

Confirm with a footer

When to use it

Use it for

Not for

Do and avoid

Do

Avoid

On a phone

Works with

Properties

States

Tokens

Built in

What you need to do

Build your next AI screen with Tattva.