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.
import { Button } from "@nesra/ui/button";import { Dialog } from "@nesra/ui/dialog";import { X } from "lucide-react";import { useState } from "react";
export function DialogBasicExample() { const [savedName, setSavedName] = useState("Alex"); const [draftName, setDraftName] = useState(savedName);
return ( <Dialog.Root> <div className="flex items-center gap-4"> <Dialog.Trigger render={<Button />} onClick={() => setDraftName(savedName)}> Edit profile </Dialog.Trigger> <span className="type-nesra-body-small-regular">Name: {savedName}</span> </div> <Dialog.Content className="p-nesra-padding-4xl"> <div className="flex items-start justify-between gap-4"> <div> <Dialog.Title>Edit profile</Dialog.Title> <Dialog.Description>Update the name shown on your account.</Dialog.Description> </div> <Dialog.Close aria-label="Close dialog" render={<Button size="icon-sm" variant="outline" />} > <X aria-hidden="true" size={16} /> </Dialog.Close> </div> <label className="mt-6 grid gap-2 type-nesra-body-small-medium"> Display name <input className="rounded-nesra-sm border border-nesra-stroke-border p-2" onChange={(event) => setDraftName(event.target.value)} value={draftName} /> </label> <div className="mt-6 flex justify-end gap-3"> <Dialog.Close render={<Button size="sm" variant="outline" />}>Cancel</Dialog.Close> <Dialog.Close onClick={() => setSavedName(draftName)} render={<Button size="sm" />}> Save </Dialog.Close> </div> </Dialog.Content> </Dialog.Root> );}Composition
Section titled “Composition”Dialog.Root├─ Dialog.Trigger└─ Dialog.Content ├─ Dialog.Title ├─ Dialog.Description ├─ task content └─ Dialog.CloseDialog.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.
Examples
Section titled “Examples”Informational
Section titled “Informational”Use a title, description, and close control for a short message.
import { Button } from "@nesra/ui/button";import { Dialog } from "@nesra/ui/dialog";
export function DialogSimpleExample() { return ( <Dialog.Root> <Dialog.Trigger render={<Button variant="outline" />}>View details</Dialog.Trigger> <Dialog.Content className="p-nesra-padding-4xl"> <Dialog.Title>Report details</Dialog.Title> <Dialog.Description className="mt-2"> This report summarizes activity from the last 30 days. </Dialog.Description> <div className="mt-6 flex justify-end"> <Dialog.Close render={<Button size="sm" />}>Done</Dialog.Close> </div> </Dialog.Content> </Dialog.Root> );}Alert Dialog
Section titled “Alert Dialog”Use role="alertdialog" for a destructive action or a critical warning that needs explicit acknowledgment.
import { Button } from "@nesra/ui/button";import { Dialog } from "@nesra/ui/dialog";import { TriangleAlert } from "lucide-react";import { useState } from "react";
export function DialogAlertExample() { const [deleted, setDeleted] = useState(false);
return ( <div className="flex items-center gap-4"> <Dialog.Root role="alertdialog"> <Dialog.Trigger disabled={deleted} render={<Button variant="destructive" />}> Delete account </Dialog.Trigger> <Dialog.Content className="p-nesra-padding-4xl"> <div className="flex items-center gap-3"> <span className="flex size-10 shrink-0 items-center justify-center rounded-full bg-nesra-categorical-red-subtle-hover text-nesra-icon-destructive"> <TriangleAlert aria-hidden="true" size={20} /> </span> <Dialog.Title>Delete account?</Dialog.Title> </div> <Dialog.Description className="mt-4"> This action cannot be undone. The account and its data will be removed from this example. </Dialog.Description> <div className="mt-8 flex justify-end gap-2"> <Dialog.Close render={<Button size="sm" variant="outline" />}>Cancel</Dialog.Close> <Dialog.Close onClick={() => setDeleted(true)} render={<Button size="sm" variant="destructive" />} > Delete account </Dialog.Close> </div> </Dialog.Content> </Dialog.Root> <span aria-live="polite" className="type-nesra-body-small-regular"> {deleted ? "Account deleted" : "Account available"} </span> </div> );}Confirmation Dialog
Section titled “Confirmation Dialog”disablePointerDismissal blocks outside presses. Escape and Cancel still dismiss this example.
Add role="alertdialog" when the confirmation also needs alert semantics.
import { Button } from "@nesra/ui/button";import { Dialog } from "@nesra/ui/dialog";import { TriangleAlert } from "lucide-react";import { useState } from "react";
export function DialogConfirmationExample() { const [deleted, setDeleted] = useState(false);
return ( <div className="flex items-center gap-4"> <Dialog.Root disablePointerDismissal> <Dialog.Trigger disabled={deleted} render={<Button variant="destructive" />}> Delete project </Dialog.Trigger> <Dialog.Content className="p-nesra-padding-4xl"> <div className="flex items-center gap-3"> <span className="flex size-10 shrink-0 items-center justify-center rounded-full bg-nesra-categorical-red-subtle-hover text-nesra-icon-destructive"> <TriangleAlert aria-hidden="true" size={20} /> </span> <Dialog.Title>Delete project?</Dialog.Title> </div> <Dialog.Description className="mt-4"> This action cannot be undone. The project will be removed from this example. </Dialog.Description> <div className="mt-8 flex justify-end gap-2"> <Dialog.Close render={<Button size="sm" variant="outline" />}>Cancel</Dialog.Close> <Dialog.Close onClick={() => setDeleted(true)} render={<Button size="sm" variant="destructive" />} > Delete </Dialog.Close> </div> </Dialog.Content> </Dialog.Root> <span aria-live="polite" className="type-nesra-body-small-regular"> {deleted ? "Project deleted" : "Project available"} </span> </div> );}Controlled state
Section titled “Controlled state”Pass open and onOpenChange when the application owns the open state.
import { Button } from "@nesra/ui/button";import { Dialog } from "@nesra/ui/dialog";import { useState } from "react";
export function DialogControlledExample() { const [open, setOpen] = useState(false);
return ( <Dialog.Root onOpenChange={setOpen} open={open}> <Dialog.Trigger render={<Button variant="outline" />}>Open settings</Dialog.Trigger> <Dialog.Content className="p-nesra-padding-4xl"> <Dialog.Title>Settings</Dialog.Title> <Dialog.Description className="mt-2"> The application controls whether this dialog is open. </Dialog.Description> <div className="mt-6 flex justify-end"> <Dialog.Close render={<Button size="sm" />}>Close settings</Dialog.Close> </div> </Dialog.Content> </Dialog.Root> );}Scrollable content
Section titled “Scrollable content”The popup caps its height to leave room above and below the panel and scrolls long content internally.
import { Button } from "@nesra/ui/button";import { Dialog } from "@nesra/ui/dialog";
const sections = Array.from({ length: 12 }, (_, index) => index + 1);
export function DialogScrollableExample() { return ( <Dialog.Root> <Dialog.Trigger render={<Button variant="outline" />}>Read report notes</Dialog.Trigger> <Dialog.Content className="p-nesra-padding-4xl"> <Dialog.Title>Report notes</Dialog.Title> <Dialog.Description className="mt-2"> The dialog surface scrolls when its content is taller than the viewport. </Dialog.Description> <div className="mt-6 space-y-4"> {sections.map((section) => ( <p className="type-nesra-body-small-regular" key={section}> Section {section}: Review the data and compare it with the previous period before sharing this report. </p> ))} </div> <div className="mt-6 flex justify-end"> <Dialog.Close render={<Button size="sm" />}>Close notes</Dialog.Close> </div> </Dialog.Content> </Dialog.Root> );}Expanded content
Section titled “Expanded content”The consuming page controls the width and inner layout. The table scrolls horizontally inside the dialog when the viewport is narrow.
import { Button } from "@nesra/ui/button";import { Dialog } from "@nesra/ui/dialog";import { X } from "lucide-react";
export function DialogExpandedExample() { return ( <Dialog.Root> <Dialog.Trigger render={<Button variant="outline" />}>Expand report</Dialog.Trigger> <Dialog.Content className="max-w-[calc(100vw-5rem)]"> <div className="flex items-start justify-between gap-4 p-nesra-padding-4xl"> <div> <Dialog.Title>Report overview</Dialog.Title> <Dialog.Description>Compare recent metrics in a wider view.</Dialog.Description> </div> <Dialog.Close aria-label="Close dialog" render={<Button size="icon-sm" variant="outline" />} > <X aria-hidden="true" size={16} /> </Dialog.Close> </div> <div className="overflow-x-auto"> <table className="w-full min-w-xl border-collapse text-left type-nesra-body-small-regular"> <thead> <tr> <th className="border-b border-nesra-stroke-border p-3">Metric</th> <th className="border-b border-nesra-stroke-border p-3">Current</th> <th className="border-b border-nesra-stroke-border p-3">Previous</th> </tr> </thead> <tbody> <tr> <td className="p-3">Views</td> <td className="p-3">12,400</td> <td className="p-3">11,800</td> </tr> </tbody> </table> </div> </Dialog.Content> </Dialog.Root> );}Dropdown inside a dialog
Section titled “Dropdown inside a dialog”The nested menu is a separate control. Choosing an item updates local state while the dialog stays open.
import { Button } from "@nesra/ui/button";import { Dialog } from "@nesra/ui/dialog";import { DropdownMenu } from "@nesra/ui/dropdown-menu";import { useState } from "react";
export function DialogWithDropdownExample() { const [action, setAction] = useState<string | null>(null);
return ( <Dialog.Root> <Dialog.Trigger render={<Button variant="outline" />}>Open report actions</Dialog.Trigger> <Dialog.Content className="p-nesra-padding-4xl"> <Dialog.Title>Report actions</Dialog.Title> <Dialog.Description className="mt-2"> Choose an action without dismissing the dialog. </Dialog.Description> <div className="mt-6"> <DropdownMenu> <DropdownMenu.Trigger render={<Button size="sm" variant="outline" />}> Choose action </DropdownMenu.Trigger> <DropdownMenu.Content align="start"> <DropdownMenu.Item onClick={() => setAction("Rename")}>Rename</DropdownMenu.Item> <DropdownMenu.Item onClick={() => setAction("Duplicate")}> Duplicate </DropdownMenu.Item> </DropdownMenu.Content> </DropdownMenu> </div> <p aria-live="polite" className="mt-4 type-nesra-body-small-regular"> {action ? `Selected: ${action}` : "No action selected"} </p> <div className="mt-6 flex justify-end"> <Dialog.Close render={<Button size="sm" />}>Close</Dialog.Close> </div> </Dialog.Content> </Dialog.Root> );}Light and Dark
Section titled “Light and Dark”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.
Accessibility
Section titled “Accessibility”- 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.disablePointerDismissalalso blocks outside press for a standard dialog.- Include
Dialog.Titleso the popup has an accessible name. AddDialog.Descriptionwhen supporting text is useful. Include aDialog.Closeinside 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.ContentforwardsinitialFocusandfinalFocusfor tasks that need a specific focus target. Check the focus order and overflow in the consuming page.
API reference
Section titled “API reference”Dialog.Root
Section titled “Dialog.Root”| 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.
Dialog.Trigger
Section titled “Dialog.Trigger”Opens the dialog. Accepts Base UI trigger props. Use render to reuse a Button.
Dialog.Content
Section titled “Dialog.Content”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.
Dialog.Title
Section titled “Dialog.Title”Names the dialog. Accepts Base UI title props and merges className with Nesra defaults.
Dialog.Description
Section titled “Dialog.Description”Describes the dialog. Accepts Base UI description props and merges className with Nesra defaults.
Dialog.Close
Section titled “Dialog.Close”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.