---
title: Dialog
description: Modal overlay with a trigger and content panel.
icon: window-maximize
---

import { ComponentPreview } from '/snippets/component-preview.mdx'

Dialogs display content in a modal overlay that focuses user attention. Like Popover, the first child becomes the trigger and the remaining children form the dialog body. An optional `title` and `description` render in the dialog header.

## Basic Usage

<ComponentPreview height="400px" json={{"view":{"type":"Dialog","title":"Crew Profile","description":"Update your details for the Heart of Gold crew manifest.","children":[{"type":"Button","label":"Edit Profile","variant":"outline","size":"default","disabled":false},{"cssClass":"gap-3","type":"Column","children":[{"type":"Label","text":"Name"},{"name":"input_4","type":"Input","inputType":"text","placeholder":"Arthur Dent","disabled":false,"readOnly":false,"required":false},{"type":"Label","text":"Designation"},{"name":"input_5","type":"Input","inputType":"text","placeholder":"Sandwich Maker","disabled":false,"readOnly":false,"required":false}]},{"cssClass":"gap-2 justify-end","type":"Row","children":[{"type":"Button","label":"Save changes","variant":"default","size":"default","disabled":false,"onClick":{"action":"closeOverlay"}}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import (
    Button,
    Column,
    Dialog,
    Input,
    Label,
    Row,
)
from prefab_ui.actions import CloseOverlay

with Dialog(
    title="Crew Profile",
    description="Update your details for the Heart of Gold crew manifest.",
):
    Button("Edit Profile", variant="outline")
    with Column(gap=3):
        Label("Name")
        Input(placeholder="Arthur Dent")
        Label("Designation")
        Input(placeholder="Sandwich Maker")
    with Row(gap=2, css_class="justify-end"):
        Button("Save changes", on_click=CloseOverlay())
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "Dialog",
    "title": "Crew Profile",
    "description": "Update your details for the Heart of Gold crew manifest.",
    "children": [
      {
        "type": "Button",
        "label": "Edit Profile",
        "variant": "outline",
        "size": "default",
        "disabled": false
      },
      {
        "cssClass": "gap-3",
        "type": "Column",
        "children": [
          {"type": "Label", "text": "Name"},
          {
            "name": "input_4",
            "type": "Input",
            "inputType": "text",
            "placeholder": "Arthur Dent",
            "disabled": false,
            "readOnly": false,
            "required": false
          },
          {"type": "Label", "text": "Designation"},
          {
            "name": "input_5",
            "type": "Input",
            "inputType": "text",
            "placeholder": "Sandwich Maker",
            "disabled": false,
            "readOnly": false,
            "required": false
          }
        ]
      },
      {
        "cssClass": "gap-2 justify-end",
        "type": "Row",
        "children": [
          {
            "type": "Button",
            "label": "Save changes",
            "variant": "default",
            "size": "default",
            "disabled": false,
            "onClick": {"action": "closeOverlay"}
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Confirmation Pattern

Dialogs work well for destructive actions that need explicit confirmation before proceeding. Use `CloseOverlay()` on the Cancel button to dismiss the dialog, and on the confirm button to close it after the action fires.

<ComponentPreview height="420px" json={{"view":{"type":"Dialog","title":"Delete Item","description":"This action cannot be undone.","children":[{"type":"Button","label":"Delete","variant":"destructive","size":"default","disabled":false},{"content":"Are you sure you want to permanently delete this item?","type":"Text"},{"cssClass":"gap-2 justify-end","type":"Row","children":[{"type":"Button","label":"Cancel","variant":"outline","size":"default","disabled":false,"onClick":{"action":"closeOverlay"}},{"type":"Button","label":"Confirm Delete","variant":"destructive","size":"default","disabled":false,"onClick":[{"action":"toolCall","tool":"delete_item","arguments":{"id":"{{ item_id }}"}},{"action":"closeOverlay"}]}]}]}}} playground=" ">
<CodeGroup>
```python Python icon="python"
from prefab_ui.components import Button, Dialog, Row, Text
from prefab_ui.actions import CloseOverlay
from prefab_ui.actions.mcp import CallTool
from prefab_ui.rx import Rx

item_id = Rx("item_id")

with Dialog(title="Delete Item", description="This action cannot be undone."):
    Button("Delete", variant="destructive")
    Text("Are you sure you want to permanently delete this item?")
    with Row(gap=2, css_class="justify-end"):
        Button("Cancel", variant="outline", on_click=CloseOverlay())
        Button(
            "Confirm Delete",
            variant="destructive",
            on_click=[
                CallTool("delete_item", arguments={"id": item_id}),
                CloseOverlay(),
            ],
        )
```
```json Protocol icon="brackets-curly"
{
  "view": {
    "type": "Dialog",
    "title": "Delete Item",
    "description": "This action cannot be undone.",
    "children": [
      {
        "type": "Button",
        "label": "Delete",
        "variant": "destructive",
        "size": "default",
        "disabled": false
      },
      {
        "content": "Are you sure you want to permanently delete this item?",
        "type": "Text"
      },
      {
        "cssClass": "gap-2 justify-end",
        "type": "Row",
        "children": [
          {
            "type": "Button",
            "label": "Cancel",
            "variant": "outline",
            "size": "default",
            "disabled": false,
            "onClick": {"action": "closeOverlay"}
          },
          {
            "type": "Button",
            "label": "Confirm Delete",
            "variant": "destructive",
            "size": "default",
            "disabled": false,
            "onClick": [
              {
                "action": "toolCall",
                "tool": "delete_item",
                "arguments": {"id": "{{ item_id }}"}
              },
              {"action": "closeOverlay"}
            ]
          }
        ]
      }
    ]
  }
}
```
</CodeGroup>
</ComponentPreview>

## Confirmation with Feedback

Wire `ShowToast` callbacks onto a `CallTool` to give feedback after the server responds. `CloseOverlay()` in the `on_success` list dismisses the dialog once the operation succeeds; `on_error` keeps the dialog open so the user can retry.

```python
from prefab_ui.components import Button, Dialog, Row, Text
from prefab_ui.actions import CloseOverlay, ShowToast
from prefab_ui.actions.mcp import CallTool
from prefab_ui.rx import Rx

user_name = Rx("user_name")
user_id = Rx("user_id")

with Dialog(title="Remove User", description="This will revoke all access."):
    Button("Remove", variant="destructive")
    Text(f"User {user_name} will lose access to all projects.")
    with Row(gap=2, css_class="justify-end"):
        Button("Cancel", variant="outline", on_click=CloseOverlay())
        Button(
            "Remove User",
            variant="destructive",
            on_click=CallTool(
                "remove_user",
                arguments={"user_id": user_id},
                on_success=[
                    ShowToast("User removed", variant="success"),
                    CloseOverlay(),
                ],
                on_error=ShowToast("{{ $error }}", variant="error"),
            ),
        )
```

## API Reference

<Card icon="code" title="Dialog Parameters">
<ParamField body="title" type="str | None" default="None">
  Dialog header title.
</ParamField>

<ParamField body="description" type="str | None" default="None">
  Dialog header description text.
</ParamField>

<ParamField body="css_class" type="str | None" default="None">
  Additional Tailwind CSS classes.
</ParamField>
</Card>

## Protocol Reference

```json Dialog
{
  "type": "Dialog",
  "children?": "[Component]",
  "let?": "object",
  "title?": "string",
  "description?": "string",
  "cssClass?": "string"
}
```

For the complete protocol schema, see [Dialog](/protocol/dialog).
