Skip to main content

​
Import

from reflex_ui import dialog

​
Description

A modal dialog component that displays content in an overlay. The dialog component supports both a high-level API for simple use cases and a compositional API for advanced customization.

​
High-Level API

dialog(
    trigger=button("Open Dialog"),
    title="Dialog Title",
    description="Dialog description text",
    content="Dialog content goes here"
)

​
Props

​
trigger
Component | None
Component that triggers the dialog when clicked
​
title
str | Component | None
The dialog title displayed in the header
​
description
str | Component | None
Additional descriptive text shown below the title
​
content
str | Component | None
Main content area of the dialog
​
default_open
bool
default:"False"
Whether the dialog is initially open. Use when uncontrolled
​
open
Var[bool] | bool
Whether the dialog is currently open. Use for controlled state
​
disable_pointer_dismissal
bool
default:"False"
When true, clicking outside the dialog won’t close it
​
modal
bool | Literal['trap-focus']
Controls modal behavior:
  • True: Focus trapped, scroll locked, pointer interactions disabled outside
  • False: User can interact with rest of document
  • 'trap-focus': Focus trapped but scroll and pointer interactions enabled

​
Event Handlers

​
on_open_change
EventHandler[bool]
Called when dialog opens or closes. Receives the new open state
​
on_open_change_complete
EventHandler[bool]
Called after animations complete when dialog opens or closes

​
Compositional API

For advanced use cases, use individual subcomponents:

​
dialog.root()

Root container component that doesn’t render its own HTML element.
​
default_open
bool
Initial open state for uncontrolled usage
​
open
Var[bool] | bool
Current open state for controlled usage
​
disable_pointer_dismissal
bool
Disable closing on outside click
​
modal
bool | Literal['trap-focus']
Modal state behavior
​
on_open_change
EventHandler[bool]
Open state change handler
​
on_open_change_complete
EventHandler[bool]
Handler called after animations complete

​
dialog.trigger()

Button that opens the dialog. Renders a <button> element.
​
native_button
bool
default:"True"
Whether to render a native button element when using render prop
​
render_
Component
Custom component to render as the trigger

​
dialog.portal()

Portals the dialog to a different part of the DOM.
​
container
str
Parent element selector to render portal into
​
keep_mounted
bool
default:"False"
Keep portal mounted in DOM while hidden

​
dialog.backdrop()

Overlay displayed beneath the popup. Renders a <div> element.
​
force_render
bool
default:"False"
Force render even when nested
​
render_
Component
Custom component to render as backdrop

​
dialog.popup()

Container for dialog contents. Renders a <div> element.
​
initial_focus
str
Element selector to focus when dialog opens
​
final_focus
str
Element selector to focus when dialog closes
​
render_
Component
Custom component to render as popup

​
dialog.title()

Heading that labels the dialog. Renders an <h2> element.
​
render_
Component
Custom component to render as title

​
dialog.description()

Paragraph with additional information. Renders a <p> element.
​
render_
Component
Custom component to render as description

​
dialog.close()

Button that closes the dialog. Renders a <button> element.
​
native_button
bool
default:"True"
Whether to render a native button element when using render prop
​
render_
Component
Custom component to render as close button

​
Class Names

Access default class names via dialog.class_names:
  • BACKDROP: Overlay background styling
  • POPUP: Dialog container styling
  • TITLE: Title text styling
  • DESCRIPTION: Description text styling
  • HEADER: Header container styling
  • CONTENT: Content container styling
  • TRIGGER: Trigger button styling
  • CLOSE: Close button styling

​
Example

import reflex as rx
from reflex_ui import dialog, button

def my_component():
    return dialog.root(
        dialog.trigger(
            render_=button("Open", variant="solid")
        ),
        dialog.portal(
            dialog.backdrop(),
            dialog.popup(
                dialog.title("Confirm Action"),
                dialog.description(
                    "Are you sure you want to proceed?"
                ),
                rx.box(
                    button("Cancel", variant="outline"),
                    button("Confirm", variant="solid"),
                    display="flex",
                    gap="2"
                )
            )
        )
    )

Build docs developers (and LLMs) love

Get started for freeTalk to us