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.

Do not use Dialog for long, multi-page workflows or sensitive confirmations; keep confirmation policy consumer-owned until the dedicated primitive ships.

1import { Button, Dialog, DialogFooter } from '@nerio-ui/ui/client';23<Dialog trigger="Open dialog" title="Share collection">4  ...5  <DialogFooter>6    <Button>Share</Button>7  </DialogFooter>8</Dialog>

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, DialogFooter } from '@nerio-ui/ui/client';

Usage

1import { Button, Dialog, DialogFooter } from '@nerio-ui/ui/client';23<Dialog trigger="Open dialog" title="Share collection">4  ...5  <DialogFooter>6    <Button>Share</Button>7  </DialogFooter>8</Dialog>

Variants

Variant	Purpose
`Task`	Short focused task with clear completion.
`Decision`	Reversible choice with an obvious escape path.

Anatomy

Slot	Purpose
`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

State changes should use shared motion tokens and preserve reduced-motion behavior.

Accessibility

Uses the Base UI Dialog primitive.
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.
Supports controlled open, uncontrolled defaultOpen, onOpenChange, and a forwarded popup ref.

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 and Typography foundation define the shared visual-role and text-resilience boundaries used by component examples. Component pages document any direction-sensitive or localizable behavior that belongs to their stable contract.

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.
`DialogFooter`	Composable footer that keeps modal actions aligned to the inline end.
`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.

Do / do not

Use for short decisions that need context without a route change.

Do not