# Dialogs, toasts, and overlays

Source: /tuil/docs/reference/components/overlays
Locale: en

Layer focus-trapped dialogs, contextual help, transient notices, and searchable command execution over an application.





## Overview [#overview]

Layer focus-trapped dialogs, contextual help, transient notices, and searchable command execution over an application.

## Installation [#installation]

<CodeBlockTabs defaultValue="npm">
  <CodeBlockTabsList>
    <CodeBlockTabsTrigger value="npm">
      npm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="pnpm">
      pnpm
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="yarn">
      yarn
    </CodeBlockTabsTrigger>

    <CodeBlockTabsTrigger value="bun">
      bun
    </CodeBlockTabsTrigger>
  </CodeBlockTabsList>

  <CodeBlockTab value="npm">
    ```bash
    npx @mwillbanks/tuil add dialog confirm-dialog tooltip toast command-palette drawer popover skeleton error-boundary
    ```
  </CodeBlockTab>

  <CodeBlockTab value="pnpm">
    ```bash
    pnpm dlx @mwillbanks/tuil add dialog confirm-dialog tooltip toast command-palette drawer popover skeleton error-boundary
    ```
  </CodeBlockTab>

  <CodeBlockTab value="yarn">
    ```bash
    yarn dlx @mwillbanks/tuil add dialog confirm-dialog tooltip toast command-palette drawer popover skeleton error-boundary
    ```
  </CodeBlockTab>

  <CodeBlockTab value="bun">
    ```bash
    bun x @mwillbanks/tuil add dialog confirm-dialog tooltip toast command-palette drawer popover skeleton error-boundary
    ```
  </CodeBlockTab>
</CodeBlockTabs>

The CLI writes source-owned components beneath the destination configured in
`tuil.config.ts`; the default import below assumes `src/components/tuil`.

<PublishedStory storyId="component-acceptance" variant="Dialog" />

## Components and subcomponents [#components-and-subcomponents]

| API                                                                            | Signature                         | Description                             |
| ------------------------------------------------------------------------------ | --------------------------------- | --------------------------------------- |
| [`Dialog`](/tuil/docs/reference/components/overlays/dialog)                         | `constant Dialog`                 | Public constant Dialog.                 |
| [`Dialog.Trigger`](/tuil/docs/reference/components/overlays/dialog-trigger)         | `subcomponent Dialog.Trigger`     | Public subcomponent Dialog.Trigger.     |
| [`Dialog.Content`](/tuil/docs/reference/components/overlays/dialog-content)         | `subcomponent Dialog.Content`     | Public subcomponent Dialog.Content.     |
| [`Dialog.Title`](/tuil/docs/reference/components/overlays/dialog-title)             | `subcomponent Dialog.Title`       | Public subcomponent Dialog.Title.       |
| [`Dialog.Description`](/tuil/docs/reference/components/overlays/dialog-description) | `subcomponent Dialog.Description` | Public subcomponent Dialog.Description. |
| [`Dialog.Confirm`](/tuil/docs/reference/components/overlays/dialog-confirm)         | `subcomponent Dialog.Confirm`     | Public subcomponent Dialog.Confirm.     |
| [`Dialog.Cancel`](/tuil/docs/reference/components/overlays/dialog-cancel)           | `subcomponent Dialog.Cancel`      | Public subcomponent Dialog.Cancel.      |
| [`ConfirmDialog`](/tuil/docs/reference/components/overlays/confirm-dialog)          | `function ConfirmDialog`          | Public function ConfirmDialog.          |
| [`Tooltip`](/tuil/docs/reference/components/overlays/tooltip)                       | `function Tooltip`                | Public function Tooltip.                |
| [`ToastProvider`](/tuil/docs/reference/components/overlays/toast-provider)          | `function ToastProvider`          | Public function ToastProvider.          |
| [`useToast`](/tuil/docs/reference/components/overlays/use-toast)                    | `function useToast`               | Public function useToast.               |
| [`Toast`](/tuil/docs/reference/components/overlays/toast)                           | `function Toast`                  | Public function Toast.                  |
| [`ToastViewport`](/tuil/docs/reference/components/overlays/toast-viewport)          | `function ToastViewport`          | Public function ToastViewport.          |
| [`CommandPalette`](/tuil/docs/reference/components/overlays/command-palette)        | `function CommandPalette`         | Public function CommandPalette.         |
| [`Drawer`](/tuil/docs/reference/components/overlays/drawer)                         | `constant Drawer`                 | Public constant Drawer.                 |
| [`Popover`](/tuil/docs/reference/components/overlays/popover)                       | `constant Popover`                | Public constant Popover.                |
| [`Skeleton`](/tuil/docs/reference/components/overlays/skeleton)                     | `function Skeleton`               | Public function Skeleton.               |
| [`ErrorBoundary`](/tuil/docs/reference/components/overlays/error-boundary)          | `class ErrorBoundary`             | Public class ErrorBoundary.             |

## Interaction [#interaction]

The top overlay receives input before application hotkeys. Escape closes dismissible overlays and focus returns to the prior node.

## API and events [#api-and-events]

Open state and selections flow through `onOpenChange`, `onPress`, command callbacks, and the toast API.

Every interactive component publishes semantic roles, labels, state, and focus
identity through the renderer's `SemanticRegistry`. Callback failures flow to
the owning application's error boundary.

<Mermaid
  chart="flowchart LR
  S0[&#x22;props and runtime state&#x22;]
  S1[&#x22;semantic registration&#x22;]
  S2[&#x22;focus and input routing&#x22;]
  S3[&#x22;callback or state update&#x22;]
  S4[&#x22;rerender&#x22;]
  S0 --> S1
  S1 --> S2
  S2 --> S3
  S3 --> S4"
/>

## Example [#example]

```tsx
import type { ComponentProps } from "react";
import { Dialog } from "@/components/tuil/feedback/overlays";

export function Example(props: ComponentProps<typeof Dialog>) {
  return <Dialog {...props} />;
}
```

Registry-installed components are source-owned: customize the generated file in
your application, and use the package reference for the shared runtime contracts.