Skip to content

Dialog

⋯

Dialog provides a modal surface near the top of the viewport with a neutral background and semantic text and border colors. An app design uses this pattern to expand a table into a large modal. Width and inner layout belong to the consuming page. A right-edge sheet in the same app is a separate layout.

Import Dialog from @nesra/ui/dialog or the package root. The example also works as a live preview.

Name: Alex
Dialog.Root
├─ Dialog.Trigger
└─ Dialog.Content
├─ Dialog.Title
├─ Dialog.Description
├─ task content
└─ Dialog.Close

Dialog.Content portals the backdrop and popup. Its default width is 100% of the available space up to 24rem. It has no default padding, so app content can reach the edges when needed. The basic example adds 24px padding. Content scrolls internally when it exceeds the available viewport height. The backdrop fades and the popup fades and scales over 150ms unless reduced motion is requested. Set className for a wider app layout, such as max-w-[calc(100vw-5rem)] for an expanded table. No Dialog size variants are defined.

Use a title, description, and close control for a short message.

Use role="alertdialog" for a destructive action or a critical warning that needs explicit acknowledgment.

Account available

disablePointerDismissal blocks outside presses. Escape and Cancel still dismiss this example. Add role="alertdialog" when the confirmation also needs alert semantics.

Project available

Pass open and onOpenChange when the application owns the open state.

The popup caps its height to leave room above and below the panel and scrolls long content internally.

The consuming page controls the width and inner layout. The table scrolls horizontally inside the dialog when the viewport is narrow.

The nested menu is a separate control. Choosing an item updates local state while the dialog stays open.

The backdrop uses --nesra-foundation-bg-overlay at 70% opacity, which is near-black in both modes. The panel uses --nesra-surface-card-bg-neutral, --nesra-stroke-border, and --nesra-text-body, and Dialog.Description uses --nesra-text-support, so the dialog follows the active theme. The alert examples tint the icon with --nesra-categorical-red-subtle-hover and --nesra-icon-destructive so the badge stays legible in Dark.

  • Modal mode is the Base UI default. It moves focus into the popup, traps focus, prevents page scroll, and restores focus to the trigger on close. Escape and outside press dismiss by default.
  • role="alertdialog" uses Base UI Alert Dialog semantics. Its outside press does not dismiss the popup. disablePointerDismissal also blocks outside press for a standard dialog.
  • Include Dialog.Title so the popup has an accessible name. Add Dialog.Description when supporting text is useful. Include a Dialog.Close inside modal content so touch screen reader users can leave.
  • The application owns form validation, saving, and any confirmation before closing. A close button does not submit or save automatically.
  • Dialog.Content forwards initialFocus and finalFocus for tasks that need a specific focus target. Check the focus order and overflow in the consuming page.
Prop Type Default Effect
open boolean — Controls open state.
defaultOpen boolean false Initializes uncontrolled open state.
onOpenChange Base UI callback — Reports open changes and dismissal reason.
modal boolean or "trap-focus" true Controls focus trap and outside interaction.
disablePointerDismissal boolean false Prevents outside press dismissal.
role "dialog" or "alertdialog" "dialog" Selects general or alert dialog semantics.

Dialog.Root forwards the remaining Base UI Dialog root props.

Opens the dialog. Accepts Base UI trigger props. Use render to reuse a Button.

Portals the backdrop and popup. Accepts Base UI popup props and container for a custom portal target. It merges className with Nesra defaults and has no default padding.

Names the dialog. Accepts Base UI title props and merges className with Nesra defaults.

Describes the dialog. Accepts Base UI description props and merges className with Nesra defaults.

Closes the dialog. Accepts Base UI close props. Use render to reuse a Button.

Dialog.Content.container defaults to document.body. The same parts are available as named exports from @nesra/ui/dialog and the package root.

See colors, typography, and shape and elevation for the underlying tokens.