DocsComponents

Dialog

A focused surface for decisions that need your attention.

Draft

Installation

Terminal

pnpm dlx shadcn@latest add https://react-toolbox.io/r/dialog.json

New here? Set up your project first. Styles, fonts, and required components are included.

Usage

Control visibility with active. Supply a title and handle dismissal using onEscKeyDown and onOverlayClick. Dialog manages focus and restores it to the trigger.

Use the Code tab above for a complete example. The import follows your configured UI alias. See Theming to customize colors, spacing, and style slots.

State and callbacks

Dialog visibility is controlled by active. Set it to false in your dismissal or action handlers. Escape and overlay callbacks report interaction; they do not change your state for you.

delay is the exit lifecycle delay, not an automatic dismissal timeout. Keep it aligned with the exit motion when customizing animation.

API reference

Generated from the installed TypeScript source. Defaults are the values declared by each function; a dash means no parameter default is declared. Forwarded props can use the receiving component’s default. Callback types show the exact arguments passed to your handler.

`Dialog`

Property	Type	Default
`actions`	`DialogActionProps[]`	`[]`
`active`	`boolean`	`false`
`delay`	`number`	`500`
`classNames`	`DialogTheme` Classes for the component's rendered parts. Applied after legacy theme overrides.	`—`
`theme`Deprecated alias	`DialogTheme` Use classNames for style slots; use ThemeProvider for design tokens.	`—`
`title`	`ReactNode`	`—`
`type`	`'small' \| 'normal' \| 'large' \| 'fullscreen' \| 'custom'`	`'normal'`
`ref`	`Ref<HTMLDivElement>`	`—`

Callbacks

Property	Type	Default
`onEscKeyDown`	`(event: KeyboardEvent) => void`	`—`
`onOverlayClick`	`MouseEventHandler<HTMLDivElement>`	`—`
`onOverlayMouseDown`	`MouseEventHandler<HTMLDivElement>`	`—`
`onOverlayMouseMove`	`MouseEventHandler<HTMLDivElement>`	`—`
`onOverlayMouseUp`	`MouseEventHandler<HTMLDivElement>`	`—`

Also inherits Omit<HTMLAttributes<HTMLDivElement>, 'title'>, except the omissions and overrides in its exported props type below. Use the supported native aria-*, data-*, event, and element attributes as appropriate.

Style slots

Pass a map of Tailwind classes to classNames. Available keys:

active
body
button
dialog
fullscreen
large
navigation
normal
small
title
wrapper

theme is the deprecated compatibility alias. When both are provided, classNames wins conflicting utilities within each slot. See Theming for tokens and override rules.

Exported TypeScript types

Expand a type to inspect its full declaration, including generic constraints, union branches, callback arguments, ref handles, and inherited props. Import these types from @/components/ui/material/dialog.

DialogTheme

tsx

type DialogTheme = Partial<
  Record<
    | 'active'
    | 'body'
    | 'button'
    | 'dialog'
    | 'fullscreen'
    | 'large'
    | 'navigation'
    | 'normal'
    | 'small'
    | 'title'
    | 'wrapper',
    string
  >
>;

DialogClassNames

tsx

type DialogClassNames = DialogTheme;

DialogActionProps

tsx

type DialogActionProps = ButtonProps;

DialogProps

tsx

interface DialogProps extends Omit<HTMLAttributes<HTMLDivElement>, 'title'> {
  actions?: DialogActionProps[];
  active?: boolean;
  delay?: number;
  onEscKeyDown?: (event: KeyboardEvent) => void;
  onOverlayClick?: MouseEventHandler<HTMLDivElement>;
  onOverlayMouseDown?: MouseEventHandler<HTMLDivElement>;
  onOverlayMouseMove?: MouseEventHandler<HTMLDivElement>;
  onOverlayMouseUp?: MouseEventHandler<HTMLDivElement>;
  /** Classes for the component's rendered parts. Applied after legacy theme overrides. */
  classNames?: DialogTheme;
  /** @deprecated Use classNames for style slots; use ThemeProvider for design tokens. */
  theme?: DialogTheme;
  title?: ReactNode;
  type?: 'small' | 'normal' | 'large' | 'fullscreen' | 'custom';
  ref?: Ref<HTMLDivElement>;
}

Material guidelines

Interrupt the current task only when a focused decision is needed. Use a clear title, concise content, and at most two related actions.
In a left-to-right dialog, place the dismissive action before the affirmative action. Name the outcome, such as Save, rather than using an ambiguous response.
Keep keyboard focus inside the open dialog and return it to the trigger on dismissal.

Material Design 1: Dialogs