Dialog

Dialog creates a fully custom modal window. Provide a content_builder= function to lay out any widgets, and a buttons= list to define the footer.

Usage

Content builder

content_builder receives an empty frame. Use it as a parent for any bootstack layout or widget:

from bootstack.dialogs import Dialog

def build(frame):
    with bs.VStack(padding=24, gap=12, parent=frame):
        bs.Label("New version available", font="heading-sm")
        bs.Label("bootstack 2.1.0 is ready to install.")

dlg = Dialog(title="Update", content_builder=build)
dlg.show()

Button roles

role= controls button styling and keyboard shortcuts automatically.

Role	Behavior
'primary'	Blue solid. Focused by default; triggered by Enter when default=True.
'secondary'	Gray solid. For neutral actions (OK, Dismiss).
'danger'	Red solid. For destructive actions. Not focused by default.
'cancel'	Gray outline. Triggered by Escape.

Reading the result

Each DialogButton carries a result= value that dialog.result is set to when that button is clicked:

dlg = Dialog(
    title="Save changes?",
    content_builder=build,
    buttons=[
        DialogButton("Save",    role="primary", result="save",    default=True),
        DialogButton("Discard", role="danger",  result="discard"),
        DialogButton("Cancel",  role="cancel"),
    ],
)
dlg.show()

if dlg.result == "save":
    save()
elif dlg.result == "discard":
    discard()

Dialog modes

mode= controls how the dialog interacts with the rest of the app.

Mode	Behavior
'modal'	Blocks the parent window until closed. Default.
'popover'	Closes automatically when focus leaves the dialog.
'sheet'	Like 'modal' on Windows/Linux; renders as a Cocoa sheet on macOS.

Positioning

By default, dialogs center on the parent window. Override with anchor_to= to position relative to a widget, the cursor, or the screen:

dlg.show(anchor_to=my_button, anchor_point="s", window_point="n")

dlg.show(anchor_to="cursor")

dlg.show(position=(400, 300))

See also

Message Dialogs — alert() and confirm() for common notifications.

Form Dialog — FormDialog for structured data-entry forms.

Filter Dialog — FilterDialog for multi-select list dialogs.

API

The complete reference for Dialog and DialogButton lives on the Dialogs API page. At a glance:

Dialog	A flexible dialog window using the builder pattern.
DialogButton	Specification for a dialog button.

Full Example

from bootstack.dialogs import Dialog, DialogButton
def show_simple():
    dlg = Dialog(
        title="Confirm deletion",
        content_builder=lambda frame: [
            bs.VStack(padding=(24, 20), gap=8, parent=frame),
            bs.Label("Delete 3 selected items?"),
            bs.Label("This action cannot be undone.", font="caption"),
        ],
        buttons=[
            DialogButton("Delete", role="danger", result="delete"),
            DialogButton("Cancel", role="cancel"),
        ],
    )
    dlg.show()

def show_info():
    def build(frame):
        with bs.VStack(padding=24, gap=12, parent=frame):
            bs.Label("New version available", font="heading-sm")
            bs.Label("bootstack 2.1.0 is ready to install.")
            bs.Label("Release notes: improved themes, new widgets.", font="caption")

    dlg = Dialog(
        title="Update available",
        content_builder=build,
        buttons=[
            DialogButton("Install now", role="primary", result="install", default=True),
            DialogButton("Later",       role="cancel"),
        ],
        min_size=(420, 180),
    )
    dlg.show()

def show_anchored():
    def build(frame):
        with bs.VStack(padding=16, gap=8, parent=frame):
            bs.Label("Saved to Documents/report.pdf")

    dlg = Dialog(
        title=" ",
        content_builder=build,
        buttons=[DialogButton("OK", role="secondary", result=True, default=True)],
        min_size=(320, 100),
    )
    dlg.show()

with bs.App(title="Dialog", size=(680, 200), padding=20, gap=16) as app:

    bs.Label("Custom Dialog", font="heading-sm")
    with bs.HStack(gap=8):
        bs.Button("Delete confirmation", on_click=show_simple)
        bs.Button("Update notice",       on_click=show_info)
        bs.Button("Simple message",      on_click=show_anchored)

app.run()