Dialog

A modal window with focus trapping, Escape to close and a backdrop; renders in a portal.

Installation

Run it from the root of a project already set up with zunoui init.

$ npx zunoui@latest add dialog

Dependencies

What add dialog installs alongside the component. The CLI skips any you already have in a compatible version.

ZUNO registry

@zuno/utils

npm

@base-ui/[email protected]

Examples

4 examples · 1 component

Modal dialog

Title, description and actions; focus returns to the trigger on close.

With a Select inside

Required composition: the Select popup opens correctly inside the dialog and in the active theme.

Large size and long title

size="lg" widens the panel; a long title wraps without running under the X.

Persistent (does not close on outside click)

dismissible={false} prevents closing on outside click and Escape; combine it with showClose={false} to require an explicit action.

API reference

Keeps the props, events and refs of the matching Base UI primitive, plus ZUNO's styles.

Prop	Type	Default
`Dialog` Root; accepts open, defaultOpen and onOpenChange.	`—`	—
`dismissible` When false, backdrop clicks and Escape do not close it: only the X or a DialogClose.	`boolean`	`true`
`DialogTrigger` Opens the dialog; use render to reuse a Button.	`button`	—
`DialogContent` Portaled backdrop and panel; traps focus. Includes a close button in the corner.	`div`	—
`size` Maximum panel width: 384, 512 or 672 px.	`"sm" \| "default" \| "lg"`	`"default"`
`showClose` Shows the close X in the corner; set it to false if the footer is the only way out.	`boolean`	`true`
`DialogTitle` Accessible title of the dialog (aria-labelledby).	`h2`	—
`DialogDescription` Associated description (aria-describedby).	`p`	—
`DialogClose` Closes the dialog.	`button`	—

States

The states that apply to this component and their visual treatment.

State	Treatment
Closed	Only the trigger; the content is not mounted needlessly.
Open	Portaled backdrop and panel; focus moves in and stays trapped.
Close	Escape or a backdrop click closes it and returns focus (if dismissible).
Non-dismissible	dismissible={false} requires an explicit footer action.

Accessibility

Always include a DialogTitle: it names the dialog for screen readers. Use DialogDescription for context.

Focus moves in on open, stays trapped inside and returns to the trigger on close. Escape and backdrop clicks close it; the panel uses theme tokens, so it keeps Light/Dark inside the portal.