Dialog

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

str | None

default:"None"

Dialog header title.

str | None

default:"None"

Dialog header description text.

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.

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.

str | None

default:"None"

Additional Tailwind CSS classes.

Protocol Reference

Dialog

{
  "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.

Get Started

Concepts

Apps

Running Prefab

Examples

Reference

Basic Usage

Confirmation Pattern

Confirmation with Feedback

State-Controlled Dialog

Non-Dismissible Dialog

API Reference

Dialog Parameters

Protocol Reference

​Basic Usage

​Confirmation Pattern

​Confirmation with Feedback

​State-Controlled Dialog

​Non-Dismissible Dialog

​API Reference

Dialog Parameters

​Protocol Reference

Basic Usage

Confirmation Pattern

Confirmation with Feedback

State-Controlled Dialog

Non-Dismissible Dialog

API Reference

Protocol Reference