;
};
Dialogs display content in a modal overlay that focuses user attention. The first child is the trigger element, the thing users click to open the dialog. Everything after the first child becomes the dialog body. An optional `title` and `description` render in the dialog header.
The dialog closes when the user clicks the X button, presses Escape, or clicks outside the overlay.
Clicking outside to dismiss may not work in the doc previews below due to how they're sandboxed. It works in deployed apps.
## Basic Usage
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"type": "Dialog",
"title": "Crew Profile",
"description": "Update your details for the Heart of Gold crew manifest.",
"dismissible": true,
"children": [
{
"type": "Button",
"label": "Edit Profile",
"variant": "outline",
"size": "default",
"disabled": false
},
{
"cssClass": "gap-3",
"type": "Column",
"children": [
{"type": "Label", "text": "Name", "optional": false},
{
"name": "input_4",
"type": "Input",
"inputType": "text",
"placeholder": "Arthur Dent",
"disabled": false,
"readOnly": false,
"required": false
},
{"type": "Label", "text": "Designation", "optional": false},
{
"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"}
}
]
}
]
}
}
```
## 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.
```python Python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"type": "Dialog",
"title": "Delete Item",
"description": "This action cannot be undone.",
"dismissible": true,
"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"}
]
}
]
}
]
}
}
```
## 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 theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
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"),
),
)
```
## State-Controlled Dialog
By default, dialogs open when the user clicks the trigger. Set `name` to bind the open state to a state variable, which lets you open the dialog programmatically via `SetState`. Both the trigger button and the external button open the same dialog:
```python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Button, Column, Dialog, Row, Text
from prefab_ui.actions import SetState
with Column(gap=3):
with Dialog(title="Help", name="show_help"):
Button("Open via trigger", variant="outline")
Text("This dialog can be opened by clicking the trigger or by any action that sets show_help to true.")
Button(
"Open via SetState",
variant="secondary",
on_click=SetState("show_help", True),
)
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"cssClass": "gap-3",
"type": "Column",
"children": [
{
"type": "Dialog",
"title": "Help",
"name": "show_help",
"dismissible": true,
"children": [
{
"type": "Button",
"label": "Open via trigger",
"variant": "outline",
"size": "default",
"disabled": false
},
{
"content": "This dialog can be opened by clicking the trigger or by any action that sets show_help to true.",
"type": "Text"
}
]
},
{
"type": "Button",
"label": "Open via SetState",
"variant": "secondary",
"size": "default",
"disabled": false,
"onClick": {"action": "setState", "key": "show_help", "value": true}
}
]
}
}
```
When `name` is set, `SetState("show_help", True)` opens the dialog and `SetState("show_help", False)` closes it. The trigger button still works too. Closing the dialog (via the X button, Escape, or clicking outside) writes `False` back to state.
This is the mechanism behind [keyboard shortcuts](/reference/app#keyboard-shortcuts): bind a key to `SetState(name, True)` to open any dialog from the keyboard.
## Non-Dismissible Dialog
Set `dismissible=False` when the user must make an explicit choice. Outside clicks, Escape, and the X button are all disabled. The only way to close the dialog is through a `CloseOverlay()` action on a button you provide:
```python icon="python" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
from prefab_ui.components import Button, Column, Dialog, Row, Text
from prefab_ui.actions import CloseOverlay
with Dialog(
title="Terms of Service",
description="You must accept to continue.",
dismissible=False,
):
Button("Review Terms")
Text("By clicking Accept, you agree to the Galactic Terms of Service.")
with Row(gap=2, css_class="justify-end"):
Button("Accept", on_click=CloseOverlay())
```
```json Protocol icon="brackets-curly" theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"view": {
"type": "Dialog",
"title": "Terms of Service",
"description": "You must accept to continue.",
"dismissible": false,
"children": [
{
"type": "Button",
"label": "Review Terms",
"variant": "default",
"size": "default",
"disabled": false
},
{
"content": "By clicking Accept, you agree to the Galactic Terms of Service.",
"type": "Text"
},
{
"cssClass": "gap-2 justify-end",
"type": "Row",
"children": [
{
"type": "Button",
"label": "Accept",
"variant": "default",
"size": "default",
"disabled": false,
"onClick": {"action": "closeOverlay"}
}
]
}
]
}
}
```
## API Reference
Dialog header title.
Dialog header description text.
State key to bind open/close state. When set, the dialog can be opened programmatically via `SetState(name, True)`. No initial state setup needed; the dialog defaults to closed.
Whether the dialog can be closed by clicking outside, pressing Escape, or the X button. When `False`, the user must use an explicit `CloseOverlay()` action.
Additional Tailwind CSS classes.
## Protocol Reference
```json Dialog theme={"theme":{"light":"snazzy-light","dark":"dark-plus"}}
{
"type": "Dialog",
"id?": "string",
"onMount?": "any",
"children?": "[Component]",
"let?": "object",
"title?": "string",
"description?": "string",
"name?": "string",
"dismissible?": true,
"cssClass?": "string"
}
```
For the complete protocol schema, see [Dialog](/protocol/dialog).