Dialog

A foundational modal component built on Radix UI primitives with accessible modal functionality, customizable styling, and flexible behavior options.

Overview

The Dialog component provides a comprehensive modal system for displaying content in overlay dialogs. It's built on top of Radix UI's Dialog primitive with additional styling and functionality, offering accessible modal behavior with customizable appearance and flexible composition patterns.

Usage

import {
  Dialog,
  DialogContent,
  DialogDescription,
  DialogFooter,
  DialogHeader,
  DialogTitle,
  DialogTrigger,
  DialogClose,
} from "@unkey/ui";
 
export default function MyComponent() {
  return (
    <Dialog>
      <DialogTrigger asChild>
        <Button>Open Dialog</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Dialog Title</DialogTitle>
          <DialogDescription>Optional description text.</DialogDescription>
        </DialogHeader>
        <div className="py-4">
          <p>Your dialog content here.</p>
        </div>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="outline">Cancel</Button>
          </DialogClose>
          <Button>Save Changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  );
}

Examples

Basic Dialog

A complete example showing various dialog patterns and configurations.

Basic Dialog

Controlled Dialog

Dialog with Close Warning

Custom Styled Dialog

Dialog without Footer

<div className="flex flex-col gap-4 w-full max-w-md mx-auto">
  {/* Basic Dialog */}
  <div className="flex flex-col gap-2">
    <h3 className="text-sm font-medium">Basic Dialog</h3>
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="outline">Open Basic Dialog</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Basic Dialog</DialogTitle>
          <DialogDescription>
            This is a basic dialog with a title and description.
          </DialogDescription>
        </DialogHeader>
        <div className="py-4">
          <p>This is the main content of the dialog.</p>
        </div>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="outline">Cancel</Button>
          </DialogClose>
          <Button>Save Changes</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  </div>

  {/* Controlled Dialog */}
  <div className="flex flex-col gap-2">
    <h3 className="text-sm font-medium">Controlled Dialog</h3>
    <Button variant="outline" onClick={() => setIsOpen(true)}>
      Open Controlled Dialog
    </Button>
    <Dialog open={isOpen} onOpenChange={setIsOpen}>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Controlled Dialog</DialogTitle>
          <DialogDescription>
            This dialog is controlled by external state.
          </DialogDescription>
        </DialogHeader>
        <div className="py-4">
          <Input
            placeholder="Enter some text..."
            value={inputValue}
            onChange={(e) => setInputValue(e.target.value)}
          />
        </div>
        <DialogFooter>
          <Button variant="outline" onClick={() => setIsOpen(false)}>
            Cancel
          </Button>
          <Button onClick={() => setIsOpen(false)}>Save</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  </div>

  {/* Dialog with Close Warning */}
  <div className="flex flex-col gap-2">
    <h3 className="text-sm font-medium">Dialog with Close Warning</h3>
    <Button variant="outline" onClick={() => setIsWarningOpen(true)}>
      Open Dialog with Warning
    </Button>
    <Dialog open={isWarningOpen} onOpenChange={setIsWarningOpen}>
      <DialogContent showCloseWarning onAttemptClose={handleCloseAttempt}>
        <DialogHeader>
          <DialogTitle>Dialog with Close Warning</DialogTitle>
          <DialogDescription>
            This dialog will show a warning when you try to close it.
          </DialogDescription>
        </DialogHeader>
        <div className="py-4">
          <p>Try clicking the X button or pressing Escape to see the warning.</p>
          <Input placeholder="Make some changes..." />
        </div>
        <DialogFooter>
          <Button variant="outline" onClick={() => setIsWarningOpen(false)}>
            Cancel
          </Button>
          <Button onClick={() => setIsWarningOpen(false)}>Save</Button>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  </div>

  {/* Custom Styled Dialog */}
  <div className="flex flex-col gap-2">
    <h3 className="text-sm font-medium">Custom Styled Dialog</h3>
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="outline">Open Custom Dialog</Button>
      </DialogTrigger>
      <DialogContent className="max-w-md bg-gradient-to-br from-blue-50 to-indigo-100 dark:from-blue-950 dark:to-indigo-900">
        <DialogHeader>
          <DialogTitle className="text-blue-900 dark:text-blue-100">
            Custom Styled Dialog
          </DialogTitle>
          <DialogDescription className="text-blue-700 dark:text-blue-300">
            This dialog has custom styling applied.
          </DialogDescription>
        </DialogHeader>
        <div className="py-4">
          <p className="text-blue-800 dark:text-blue-200">
            The content area can be styled with custom classes.
          </p>
        </div>
        <DialogFooter>
          <DialogClose asChild>
            <Button variant="outline">Close</Button>
          </DialogClose>
        </DialogFooter>
      </DialogContent>
    </Dialog>
  </div>

  {/* Dialog without Footer */}
  <div className="flex flex-col gap-2">
    <h3 className="text-sm font-medium">Dialog without Footer</h3>
    <Dialog>
      <DialogTrigger asChild>
        <Button variant="outline">Open Simple Dialog</Button>
      </DialogTrigger>
      <DialogContent>
        <DialogHeader>
          <DialogTitle>Simple Dialog</DialogTitle>
          <DialogDescription>This dialog doesn't have a footer section.</DialogDescription>
        </DialogHeader>
        <div className="py-4">
          <p>Sometimes you don't need action buttons in the footer.</p>
        </div>
      </DialogContent>
    </Dialog>
  </div>
</div>

Features

Accessible: Built on Radix UI primitives with full accessibility support
Flexible: Composable components for custom layouts
Close Warning Support: Optional confirmation when closing dialogs
Keyboard Navigation: Full keyboard support including Escape to close
Customizable: Extensive styling options through className props
TypeScript: Full TypeScript support with proper type definitions
Dark Mode Support: Consistent appearance in light and dark themes
Responsive Design: Adapts to different screen sizes

Props

Dialog

Prop	Type	Default	Description
`open`	`boolean`	-	Controls the open state of the dialog
`onOpenChange`	`(value: boolean) => void`	-	Callback when the open state changes
`children`	`ReactNode`	-	The dialog content

DialogContent

Prop	Type	Default	Description
`showCloseWarning`	`boolean`	`false`	Whether to show warning when closing
`onAttemptClose`	`() => void`	-	Callback when user attempts to close
`xButtonRef`	`RefObject<HTMLButtonElement>`	-	Ref for the close button
`className`	`string`	-	Additional classes for the dialog content
`children`	`ReactNode`	-	The content to display in the dialog

DialogTrigger

Prop	Type	Default	Description
`asChild`	`boolean`	`false`	Whether to render as child element
`children`	`ReactNode`	-	The trigger element

DialogClose

Prop	Type	Default	Description
`asChild`	`boolean`	`false`	Whether to render as child element
`children`	`ReactNode`	-	The close trigger element

DialogHeader

Prop	Type	Default	Description
`className`	`string`	-	Additional classes for header
`children`	`ReactNode`	-	Header content

DialogFooter

Prop	Type	Default	Description
`className`	`string`	-	Additional classes for footer
`children`	`ReactNode`	-	Footer content

DialogTitle

Prop	Type	Default	Description
`className`	`string`	-	Additional classes for title
`children`	`ReactNode`	-	Title content

DialogDescription

Prop	Type	Default	Description
`className`	`string`	-	Additional classes for description
`children`	`ReactNode`	-	Description content

Structure

The Dialog component is composed of several sub-components that work together:

Dialog - The root component that manages dialog state
DialogTrigger - The element that opens the dialog
DialogContent - The main dialog container with overlay
DialogHeader - Container for title and description
DialogTitle - The dialog's title
DialogDescription - Optional description text
DialogFooter - Container for action buttons
DialogClose - Component that closes the dialog when clicked

Styling

The Dialog component comes with default styling that includes:

Overlay: Semi-transparent backdrop with blur effect
Content: Centered modal with shadow and rounded corners
Animations: Smooth enter/exit animations
Responsive: Adapts to different screen sizes
Dark Mode: Full dark mode support

Custom Styling

You can customize the appearance using className props:

<DialogContent className="max-w-md bg-gradient-to-br from-blue-50 to-indigo-100">
  <DialogHeader>
    <DialogTitle className="text-blue-900">Custom Title</DialogTitle>
    <DialogDescription className="text-blue-700">
      Custom description styling
    </DialogDescription>
  </DialogHeader>
</DialogContent>

Accessibility

The Dialog component implements the following accessibility features:

Focus Management: Automatically manages focus within the dialog
Keyboard Navigation: Full keyboard support (Escape to close, Tab navigation)
ARIA Attributes: Proper ARIA labels and roles for screen readers
Focus Trap: Prevents focus from leaving the dialog when open
Screen Reader Support: Announces dialog state changes

Dialog

Basic Dialog

Controlled Dialog

Dialog with Close Warning

Custom Styled Dialog

Dialog without Footer

On this page