Dialog
Dialogs focus a short decision or task above the current product surface.
Overview and decision boundary
Use Dialog to focus a short task, confirmation, or decision above the current surface.
Do not use Dialog for long, multi-page workflows.
Preview
import { Button, Dialog, DialogFooter } from '@nerio-ui/ui/client';<Dialog trigger="Open dialog" title="Share collection"> ... <DialogFooter> <Button variant="secondary">Cancel</Button> <Button>Share</Button> </DialogFooter></Dialog>Installation and imports
Install the editable registry source, or use the matching package entrypoint when the product keeps Nerio as a workspace dependency.
pnpm dlx nerio add dialogimport { Button, Dialog, DialogFooter } from '@nerio-ui/ui/client';Usage
import { Button, Dialog, DialogFooter } from '@nerio-ui/ui/client';<Dialog trigger="Open dialog" title="Share collection"> ... <DialogFooter> <Button variant="secondary">Cancel</Button> <Button>Share</Button> </DialogFooter></Dialog>Variants
| Variant | Purpose |
|---|---|
Task | Short focused task with clear completion. |
Confirmation | Decision point for sensitive actions. |
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 heading. |
description | Optional supporting context. |
body | Task, decision, and action content. |
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.
- Includes a title and optional description.
- 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.
API
| Prop | Purpose |
|---|---|
trigger | React node or text that opens the dialog. |
title / description | Accessible dialog heading and optional context. |
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 6 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, confirmation, or decision above the current surface.
Do / do not
Do
Use for short decisions that need context without a route change.
Do not
Do not use Dialog for long, multi-page workflows.
Related components
Tokens
These are the primary customization points. Override semantic or component tokens instead of changing component source.
| Token | Purpose |
|---|---|
--n-dialog-width-md | Public customization point for this component contract. |
--n-dialog-viewport-inset | Public customization point for this component contract. |
--n-dialog-padding | Public customization point for this component contract. |
--n-dialog-header-gap | Public customization point for this component contract. |
--n-dialog-header-margin | Public customization point for this component contract. |
--n-dialog-body-gap | Public customization point for this component contract. |
--n-overlay-z-index | Public customization point for this component contract. |
--n-overlay-background | Public customization point for this component contract. |
--n-overlay-border | Public customization point for this component contract. |
--n-overlay-backdrop | Public customization point for this component contract. |
--n-overlay-backdrop-filter | Public customization point for this component contract. |
--n-overlay-foreground | Public customization point for this component contract. |
--n-overlay-foreground-muted | Public customization point for this component contract. |
--n-overlay-control-background | Public customization point for this component contract. |
--n-overlay-control-background-hover | Public customization point for this component contract. |
--n-overlay-surface-filter | Public customization point for this component contract. |
--n-overlay-shadow | Public customization point for this component contract. |
--n-input-background-on-overlay | Public customization point for this component contract. |
--n-input-background-on-overlay-hover | Public customization point for this component contract. |
--n-input-foreground-on-overlay | Public customization point for this component contract. |
--n-input-placeholder-on-overlay | Public customization point for this component contract. |
--n-motion-overlay-enter-duration | Public customization point for this component contract. |
--n-motion-overlay-enter-easing | Public customization point for this component contract. |
--n-motion-overlay-exit-duration | Public customization point for this component contract. |
--n-motion-overlay-exit-easing | Public customization point for this component contract. |
--n-focus-ring | Public customization point for this component contract. |