Skip to main content

Documentation Index

Fetch the complete documentation index at: https://prefab.prefect.io/docs/llms.txt

Use this file to discover all available pages before exploring further.

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

​
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.

​
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. 
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: 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: 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:

​
API Reference

Dialog Parameters

​
title
str | None
default:"None"
Dialog header title.
​
description
str | None
default:"None"
Dialog header description text.
​
name
str | None
default:"None"
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.
​
dismissible
bool
default:"True"
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.
​
css_class
str | None
default:"None"
Additional Tailwind CSS classes.

​
Protocol Reference

Dialog
{
  "type": "Dialog",
  "children?": "[Component]",
  "let?": "object",
  "title?": "string",
  "description?": "string",
  "name?": "string",
  "dismissible?": "boolean (default: true)",
  "cssClass?": "string"
}
For the complete protocol schema, see Dialog.