Dialog

When to useLink to "When to use"

• A decision that blocks the work: "Discard changes?", "Delete 3 files?".
• A short, focused form that belongs to the current page (rename, edit details).

Use something else when:

• the content belongs next to a button and can stay open while working: Popover
• it is a list of commands: Menu
• it is a side panel or a phone-style drawer: Sheet
• it is a message that needs no answer: a Notice or a Toast

UsageLink to "Usage"

import { Button, Dialog, TextField } from "@arshad-shah/cynosure";

const [open, setOpen] = useState(false);

<Button onClick={() => setOpen(true)}>Edit profile</Button>
<Dialog
  open={open}
  onOpenChange={setOpen}
  title="Edit profile"
  description="Changes are saved to your account."
  actions={
    <>
      <Button onClick={() => setOpen(false)}>Cancel</Button>
      <Button variant="solid" tone="accent" onClick={save}>Save</Button>
    </>
  }
>
  <TextField label="Name" />
</Dialog>

Put Cancel first and the main action last. The content scrolls between the title and the actions, so long forms keep both in view.

ConfirmationsLink to "Confirmations"

With dismissible={false} there is no close button and Escape and the backdrop do nothing: the person must pick one of your actions. Focus starts on the first action, so put the safe one first.

Content and stateLink to "Content and state"

The content is in the DOM only while the dialog is open. It mounts when the dialog opens and unmounts once it has faded out, so every opening starts fresh: fields are back at their defaults, and a closed dialog costs nothing to render.

Set keepMounted to keep the content in the DOM while closed. Use it when what the person typed must survive closing, or when the content is expensive to rebuild. Or keep the state outside the dialog, in the component that owns open.

<Dialog open={open} onOpenChange={setOpen} title="New message" keepMounted>
  <TextArea label="Message" />
</Dialog>

PropsLink to "Props"

Behaviour and accessibilityLink to "Behaviour and accessibility"

• Focus: on open, focus moves to the first control in the content, else the first action, else the dialog itself. On close it returns to where it was, usually the button that opened it.
• Mounting: closed, the <dialog> element is empty, on the server too. The content is rendered in the same render that opens it and removed when the closing transition ends, or at once when there is none (reduced motion). Reopening before the fade has finished keeps the content. With keepMounted it always stays.
• Role: a native modal <dialog>, named by title (an h2) and described by description.
• Narrow containers: below 36rem wide, the dialog docks to the bottom edge at full width.
• Isolation: it never writes to <html> or <body>. There is no scroll lock; the content uses overscroll-behavior: contain so scrolling it does not move the page.
• Toasts: inside a Toaster, toasts raised while the dialog is open show above it (not under its backdrop), and move back to the page when it closes.
• Shadow DOM: works inside shadow roots (extension content scripts).
• Motion: a short fade and scale (a slide as a sheet), removed under reduced motion.

TouchLink to "Touch"

The close button keeps a 44px hit area on coarse pointers. A tap on the backdrop closes the dialog, and the bottom-sheet actions stay above the home indicator.

ThemingLink to "Theming"

Tokens: --cy-dialog-radius, --cy-dialog-padding, --cy-dialog-width-{sm,md,lg} and --cy-dialog-scrim.

createTheme({ components: { dialog: { radius: "10px", widthMd: "520px", scrim: "rgb(0 0 0 / 0.6)" } } });

RelatedLink to "Related"

Sheet · Popover · Menu · DialogBase