Dialog

A window overlaid on either the primary window or another dialog window, rendering the content underneath inert.

❯buridan add dialog

Component Guide

Use the following to build the Dialog component.

from components.ui.dialog import dialog

dialog.root(
    dialog.trigger(),
    dialog.portal(
        dialog.backdrop(),
        dialog.popup(
            dialog.title(),
            dialog.description(),
            dialog.close(),
        ),
    ),
)

Source Code & Dependencies

For manual installation, copy each of the source codes below in their respective locations.

components/core/core.py

components/ui/dialog.py

Examples

Custom Close Button

Replace the default close control with your own button. Apply dialog.class_names.CLOSE_ICON to it for correct top-right positioning.

Props used: class_name on the button passed to dialog.close.

import reflex as rx

from components.core.hugeicon import hi
from components.ui.button import button
from components.ui.dialog import dialog
from components.ui.input import input


def dialog_close_button() -> rx.Component:
    return dialog.root(
        dialog.trigger(button("Share", variant="outline")),
        dialog.popup(
            dialog.header(
                dialog.title("Share link"),
                dialog.description(
                    "Anyone who has this link will be able to view this."
                ),
            ),
            rx.el.div(
                rx.el.div(
                    rx.el.label("Link", html_for="link", class_name="sr-only"),
                    input(
                        id="link",
                        default_value="https://ui.buridan.com/docs/getting-started/installation",
                        read_only=True,
                    ),
                    class_name="grid flex-1 gap-2",
                ),
                class_name="flex items-center gap-2",
            ),
            dialog.footer(
                dialog.close(button("Close", type="button")),
                class_name="sm:justify-start",
            ),
            dialog.close(
                button(
                    hi("Cancel01Icon", class_name="size-4"),
                    variant="ghost",
                    size="icon-sm",
                    class_name=dialog.class_names.CLOSE_ICON,
                )
            ),
            class_name="sm:max-w-md",
        ),
    )

No Close Button

To omit the top-right close icon, simply don't render a dialog.close(...) for it — every other close mechanism (Escape, backdrop click, a footer button) still works.

Props used: none required — omit the icon dialog.close(...) call.

import reflex as rx

from components.ui.button import button
from components.ui.dialog import dialog


def dialog_no_close_button() -> rx.Component:
    return dialog.root(
        dialog.trigger(button("No Close Button", variant="outline")),
        dialog.popup(dialog.header(
            dialog.title("No Close Button"),
            dialog.description(
                "This dialog doesn't have a close button in the top-right corner."
            ),
        ),)
    )

Keep actions visible while the content scrolls, using dialog.footer.

Props used: none required beyond standard dialog.footer composition.

import reflex as rx

from components.core.hugeicon import hi
from components.ui.button import button
from components.ui.dialog import dialog


def dialog_sticky_footer() -> rx.Component:
    return dialog.root(
        dialog.trigger(button("Sticky Footer", variant="outline")),
        dialog.popup(
            dialog.header(
                dialog.title("Sticky Footer"),
                dialog.description(
                    "This dialog has a sticky footer that stays visible while the content scrolls."
                ),
            ),
            rx.el.div(
                *[
                    rx.el.p(
                        "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed do "
                        "eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut "
                        "enim ad minim veniam, quis nostrud exercitation ullamco laboris "
                        "nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in "
                        "reprehenderit in voluptate velit esse cillum dolore eu fugiat "
                        "nulla pariatur. Excepteur sint occaecat cupidatat non proident, "
                        "sunt in culpa qui officia deserunt mollit anim id est laborum.",
                        class_name="mb-4 leading-normal",
                    )
                    for _ in range(10)
                ],
                class_name="-mx-4 no-scrollbar max-h-[50vh] overflow-y-auto px-4",
            ),
            dialog.footer(
                dialog.close(button("Close", variant="outline")),
            ),
            dialog.close(
                button(
                    hi("Cancel01Icon", class_name="size-4"),
                    variant="ghost",
                    size="icon-sm",
                    class_name=dialog.class_names.CLOSE_ICON,
                )
            ),
        )
    )

API Reference

dialog.root

Non-visual scoping wrapper (display: contents, adds no layout box). Trigger and close resolve their target <dialog> by walking up to the nearest dialog.root — no manual id threading, and multiple independent dialogs on the same page (e.g. a per-row "Share" dialog) never cross-target each other.

dialog.root(
    dialog.trigger(button("Share", variant="outline")),
    dialog.popup(...),
)

Prop	Type	Default
`class_name`	`str`	`""`

dialog.trigger

Wraps its child (typically a button(...)) with a capturing click listener that calls .showModal() on the nearest dialog.popup. No visual box of its own, so nesting a styled button inside doesn't add extra layout depth.

dialog.trigger(button("Share", variant="outline"))

Prop	Type	Default
`id`	`str`	auto-generated
`class_name`	`str`	`""`

dialog.popup

Renders the native <dialog>. Escape and backdrop clicks both close it when dismissible=True (the default).

dialog.popup(
    dialog.header(dialog.title("Share link")),
    ...,
)

Prop	Type	Default
`dismissible`	`bool`	`True`
`on_open_change`	`EventHandler[[bool]] \\| None`	`None`
`class_name`	`str`	`""`

When dismissible=False, both Escape and backdrop-click are disabled — only an explicit dialog.close(...) can close it.

dialog.close

Same behavioral wrapper as dialog.trigger, but calls .close(). Has no default visual styling of its own — apply dialog.class_names.CLOSE / dialog.class_names.CLOSE_ICON to whatever you pass in.

dialog.close(button("Close", type="button"))

dialog.close(
    button(
        hi("Cancel01Icon", class_name="size-4"),
        variant="ghost",
        size="icon-sm",
        class_name=dialog.class_names.CLOSE_ICON,
    )
)

Prop	Type	Default
`id`	`str`	auto-generated
`class_name`	`str`	`""`

dialog.title

dialog.title("Share link")

Prop	Type	Default
`class_name`	`str`	`""`

dialog.description

dialog.description("Anyone who has this link will be able to view this.")

Prop	Type	Default
`class_name`	`str`	`""`

dialog.header

dialog.header(
    dialog.title("Share link"),
    dialog.description("..."),
)

Prop	Type	Default
`class_name`	`str`	`""`

dialog.footer

dialog.footer(dialog.close(button("Close", type="button")))

Prop	Type	Default
`class_name`	`str`	`""`