Dialog

Dialogs focus a short decision or task above the current product surface.

Overview and decision boundary

Use Dialog to focus a short task or reversible decision above the current surface; use AlertDialog when a consequential action requires an explicit response.

Do not use Dialog for long workflows or consequential confirmation that belongs in AlertDialog.

1import { Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from '@nerio-ui/ui/client';23<Dialog trigger="Open dialog" title="Share collection">...</Dialog>45<DialogRoot>6  <DialogTrigger render={<Button>Open custom dialog</Button>} />7  <DialogPortal>8    <DialogContent>9      <DialogHeader>10        <DialogTitle>Move collection</DialogTitle>11        <DialogDescription>Choose a destination workspace.</DialogDescription>12      </DialogHeader>13      ...14      <DialogFooter>15        <DialogClose render={<Button variant="secondary">Cancel</Button>} />16        <Button>Move collection</Button>17      </DialogFooter>18    </DialogContent>19  </DialogPortal>20</DialogRoot>

Installation and imports

Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.

1pnpm exec nerio add dialog23import { Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from '@nerio-ui/ui/client';

Usage

1import { Button, Dialog, DialogClose, DialogContent, DialogDescription, DialogFooter, DialogHeader, DialogPortal, DialogRoot, DialogTitle, DialogTrigger } from '@nerio-ui/ui/client';23<Dialog trigger="Open dialog" title="Share collection">...</Dialog>45<DialogRoot>6  <DialogTrigger render={<Button>Open custom dialog</Button>} />7  <DialogPortal>8    <DialogContent>9      <DialogHeader>10        <DialogTitle>Move collection</DialogTitle>11        <DialogDescription>Choose a destination workspace.</DialogDescription>12      </DialogHeader>13      ...14      <DialogFooter>15        <DialogClose render={<Button variant="secondary">Cancel</Button>} />16        <Button>Move collection</Button>17      </DialogFooter>18    </DialogContent>19  </DialogPortal>20</DialogRoot>

Variants

Variant	Purpose
`Convenience`	Compatible trigger, title, description, body, footer, and close path.
`Compound`	Meaningful parts may be omitted, reordered, or customized while Base UI retains behavior.

Anatomy

Slot	Purpose
`trigger`	Control that opens the dialog.
`portal`	Optional container boundary for portalled modal content.
`backdrop`	Backdrop that separates the dialog from the page.
`content`	Modal surface rendered through a portal.
`header`	Title, optional description, and close boundary.
`heading`	Grouped title and optional description.
`title`	Required accessible dialog name; renders as a neutral 16 px div by default.
`description`	Optional supporting context using the standard 14 px body size.
`body`	Task, decision, and action content that scrolls within the viewport boundary.
`footer`	Optional action row aligned to the inline end.
`close`	Secondary icon Button with a localizable accessible name.

States

State	Purpose
`Open`	Focus moves into the dialog.
`Closed`	Focus returns to the trigger.

Motion

overlay entry and exit
reduced-motion fade-only state change

Accessibility

Uses the Base UI Dialog primitive.
The existing Dialog convenience API remains compatible; DialogRoot, DialogTrigger, DialogPortal, DialogBackdrop, DialogContent, DialogHeader, DialogTitle, DialogDescription, DialogBody, DialogFooter, and DialogClose expose meaningful compound anatomy.
The title renders as a neutral 16px div by default; titleAs opts into h2-h6 only when the title belongs in the document outline. The optional description uses the standard 14px body size.
Focus is trapped while the dialog is open and returns to the trigger on close.
Defaults closeLabel to "Close dialog" for the secondary icon Button; provide a localized accessible name when needed.
Compound DialogContent supports deliberate initialFocus and finalFocus targets while every modal composition retains a keyboard-reachable DialogClose.
Supports controlled open, uncontrolled defaultOpen, onOpenChange, and forwarded trigger, portal, backdrop, content, title, description, body, footer, and close refs.

Review the shared responsibility and evidence boundaries in the Accessibility foundation alongside this component-specific contract. Use the Spacing & layout foundation for shared density, wrapping, overflow, reflow, and component-versus-product ownership guidance. The Color foundation, Typography foundation, and Localization foundation define the shared visual-role, text-resilience, direction, and locale boundaries used by component examples.

API

Prop	Purpose
`trigger`	React node or text that opens the dialog.
`title / description`	Accessible dialog name and optional context. titleAs opts into h2-h6 only when the title belongs in the document outline.
`bodyClassName`	Optional class hook for the body slot.
`DialogRoot and compound parts`	Expose Trigger, Portal, Backdrop, Content, Header, Title, Description, Body, Footer, and Close without changing the convenience Dialog API.
`closeLabel`	Accessible close-control name; defaults to "Close dialog".

Implementation contract

Contract	Value
`Registry item`	dialog installs 7 source files into the configured components directory.
`Base UI`	dialog
`Registry dependencies`	button
`Package dependencies`	@base-ui/react, @nerio-ui/adapters, clsx, react, tailwind-merge, tailwindcss

Styling contract

Contract	Value
`Authoring`	`Complete, statically detectable Tailwind CSS v4 recipes own component visuals.`
`Values`	`Semantic and component --n-* variables remain the canonical customization layer.`
`Overrides`	`Customizable slots merge consumer className values with tailwindCn so conflicting utilities resolve deterministically.`
`Residual CSS`	`Only shared keyframes and scoped no-Preflight compatibility rules remain; there is no parallel visual selector layer.`

Design notes

Use Dialog to focus a short task or reversible decision above the current surface; use AlertDialog when a consequential action requires an explicit response.

Do / do not

Use the convenience API for the common path and compound parts only when the task needs structural control.

Do not