Dialog
A modal primitive: dimmed backdrop, centered panel with header / body / footer slots, Esc and backdrop-click dismissal, and body-scroll lock while open. It floats above the rest of the page, unaffected by any clipping ancestor.
Basic
A simple confirm dialog with title, eyebrow, body text, and an action footer.
Growing content
When the content changes height while the dialog is open — a section expands,
an error line appears, a multi-step dialog moves to its next step — the panel
glides to its new height (220ms, quick then slow) instead of jumping, and stays
centred as it does. A Collapsible inside is followed as it animates, so the
two never fight. The panel still caps at 85% of the viewport; past that only the body
scrolls — the title row and the footer stay in view — and the edge with more
content fades over 12px so a cut line reads as "keep scrolling". Modal and AlertDialog do the same. Reduced motion: no glide.
Long eyebrow
The eyebrow often names the resource the dialog acts on, so it can be any length. It takes only the room the title leaves and ellipsizes before the close button; the title keeps its words and truncates only if it alone is wider than the row.
Publish dataset
A real-world form: a text input for the dataset family name, a radio list of
source bindrs, and a primary publish action. Demonstrates building form fields
inside the dialog body using design tokens — uppercase mono labels, underlined
inputs, custom radio dots that fill with var(--uikit-accent) when picked.
Managed keyboard focus
Opt in with managedFocus for forms and multi-step workflows. The existing
Floating UI focus manager contains keyboard focus, ignores hidden/disabled
controls, and returns focus on close. Nested UIKit floating portals remain
interactive. initialFocus accepts a tabbable index or an element ref;
returnFocus accepts a trigger ref when the opener was in a menu that unmounted.
Supply a visible title or aria-label for the dialog's accessible name.
Behavior
- Floats above the page — the dialog appears above all other content and is never clipped by an overflow-hidden, transformed, or sticky ancestor.
- Body scroll lock — the page behind the dialog can't scroll while it's open; scrolling is restored on close.
- Esc + backdrop dismissal — both routes call the same
onClosehandler. Caller controls whether to honor the dismissal (e.g. confirm before closing if there are unsaved edits). - Theme-aware — the backdrop dims the page and the panel uses the surface and shadow tokens, so it flips automatically in dark mode.
- Spring pop — the panel enters from its centre in 340ms (scale .85 →
1.035 → .995 → 1 while fading in) and exits in 160ms (scale 1 → .95, fading
out). The backdrop fades its colour in over 180ms and out over 150ms at the
same time. The panel stays in the DOM until its exit ends, showing the last
open title, body and footer; it is inert and hidden from assistive
technology meanwhile. Esc, scroll lock and focus return still release the
moment
openturns false. Reduced motion fades without scaling. See Motion.
Opt-in focus management —
managedFocusdefaults to false to preserve existing consumers. Enable it for keyboard workflows instead of adding a second product-level document focus trap.
Props
| Prop | Type | Default | Description |
|---|---|---|---|
open | boolean | — | Required. Controlled open state. |
onClose | () => void | — | Required. Fires when the user dismisses the dialog (Esc key, backdrop click, or any explicit close affordance the caller renders). Caller must flip open to false. |
title | ReactNode | — | Heading rendered top-left of the panel. 17px semibold ink. |
eyebrow | string | — | Small uppercase mono label rendered next to the title. Takes the room the title leaves and ellipsizes; the title never yields to it. |
footer | ReactNode | — | Footer content. Typically a row of action buttons aligned right. |
width | number | 480 | Panel width in px. |
showEscHint | boolean | true | Show the muted "esc" hint in the header. Clicking it also calls onClose. |
dismissOnBackdropClick | boolean | true | Dismiss when the user clicks the dimmed backdrop. |
dismissOnEsc | boolean | true | Dismiss when the user presses Escape. |
className | string | — | Extra classes on the panel element. |
managedFocus | boolean | false | Contain modal focus with the existing Floating UI focus manager. |
initialFocus | number | RefObject<HTMLElement | null> | 0 | Initial tabbable index or explicit element; managed mode only. |
returnFocus | boolean | RefObject<HTMLElement | null> | true | Restore the opener or explicit trigger; managed mode only. |
aria-label | string | — | Accessible name if no visible title is supplied. |
children | ReactNode | — | Body content — typically form fields, message text, or a custom layout. |