Basel Standard / Docs

Dialog

Centered overlay for focused decisions, short editing tasks, and temporary interruption.

Dialogs interrupt the current page on purpose. They are useful when the user should complete one bounded task or confirm a decision before returning to the underlying layout. In this system the dialog remains spare and structural so the content, not the chrome, defines the priority.

Installation

Install

Purchase access, then open /account/install to issue a registry token.

Usage

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
} from "@/components/ui/dialog"

<Dialog>
  <DialogTrigger asChild>
    <Button>Open dialog</Button>
  </DialogTrigger>
  <DialogContent>
    <DialogHeader>
      <DialogTitle>Publish issue</DialogTitle>
      <DialogDescription>Confirm the release before it goes live.</DialogDescription>
    </DialogHeader>
  </DialogContent>
</Dialog>

Why This Primitive Exists

Some actions deserve a pause. A dialog creates that pause without sending the user to a new route or forcing a full-screen workflow.

Use it for short forms, confirmations, and bounded review tasks.
Prefer it when the user should finish one thing before continuing.
Avoid it for long forms, complex navigation, or content that belongs directly on the page.

Examples

Basic Confirmation

The default pattern is a trigger, a clear title, one short explanation, and a small action row.

<DialogContent>
  <DialogHeader>
    <DialogTitle>Publish issue 06</DialogTitle>
    <DialogDescription>
      Publishing makes the issue visible in the archive.
    </DialogDescription>
  </DialogHeader>
  <DialogFooter>{/* actions */}</DialogFooter>
</DialogContent>

Short Editing Task

Dialogs work for compact edit flows when the user can complete the task without scrolling through a page-length form.

<div className="grid gap-4">
  <Label htmlFor="title">Title</Label>
  <Input id="title" />
</div>

In Context

Place the trigger close to the workflow it affects. That keeps the interruption legible and local.

Confirmation surface

Use dialogs when the user should pause before crossing a boundary.

The trigger sits inside the workflow card so the interruption still feels local to the task.

<CardFooter>
  <Dialog>
    <DialogTrigger asChild>
      <Button>Publish issue</Button>
    </DialogTrigger>
  </Dialog>
</CardFooter>

Guidance

Use Interruption Sparingly

Open a dialog when the user should stop and decide.
Keep routine actions on the page when interruption adds no clarity.
If the content needs navigation, tabs, or long explanation, use a sheet, drawer, or route instead.

Keep The Scope Narrow

One task per dialog.
Keep titles direct and descriptions specific.
Limit footer actions to the real decision points.

Preserve Local Context

Put the trigger near the content or action that caused the dialog.
Use asChild on DialogTrigger when the trigger should remain a Button or link.
If the task is mobile-first and should rise from the bottom edge, use Drawer instead.

API Reference

Core Exports

Export	Renders	Notes
`Dialog`	`DialogPrimitive.Root`	Root state container.
`DialogTrigger`	`DialogPrimitive.Trigger`	Opens the dialog, commonly via `asChild`.
`DialogPortal`	`DialogPrimitive.Portal`	Portal wrapper for overlay and content.
`DialogOverlay`	`DialogPrimitive.Overlay`	Full-screen overlay with the shared dimmed treatment.
`DialogContent`	`DialogPrimitive.Content`	Centered panel with built-in close button.
`DialogHeader`	`div`	Layout wrapper for title and description.
`DialogFooter`	`div`	Action row with responsive stacking and a top border.
`DialogTitle`	`DialogPrimitive.Title`	Large uppercase title.
`DialogDescription`	`DialogPrimitive.Description`	Supporting body copy.
`DialogClose`	`DialogPrimitive.Close`	Manual close control when you need it in custom layouts.

Notable Props

Export	Prop	Type	Notes
`Dialog`	`open`, `defaultOpen`, `onOpenChange`	Radix dialog root props	Supports controlled and uncontrolled use.
`DialogTrigger`	`asChild`	`boolean`	Lets a `Button`, link, or custom trigger keep its own element type.
`DialogContent`	`className` plus Radix content props	content props	Use for width or layout adjustments, not for rewriting the core structure.
`DialogClose`	`asChild`	`boolean`	Useful in footers when a visible cancel action should close the dialog.

The dialog is a Swiss wrapper around Radix Dialog, so focus management, escape handling, and accessibility semantics come from the underlying primitive.

Previous: Context Menu Next: Drawer