Modal

Modals are "dialogs" that appear in front of the application content. They provide critical information, require user confirmation, or host complex forms.

Bootstrap Reference

Bootstrap 5 Modals

Quick Start

Live Preview

# The Trigger
trigger = Button("Launch Modal", data_bs_toggle="modal", data_bs_target="#myModal")

# The Modal Definition
modal = Modal(
    "Hello! This is a modal dialog.", 
    title="Example Modal", 
    modal_id="myModal",
    footer=Button("Save", variant="primary")
)

Visual Examples & Use Cases

1. Sizing

Specify the viewport width using size.

Live Preview (Sizing)

Modal(..., size="sm") # Small
Modal(..., size="lg") # Large

2. Centered & Scrollable

Handle long content or improve ergonomics by centering the dialog.

Live Preview (Centered)

Modal(
    "This modal is centered on the screen.", 
    centered=True, 
    title="Vertically Centered"
)

3. Static Backdrop

Prevents closing the modal when clicking the shaded background. Useful for high-stakes forms or "must-read" alerts.

Modal(..., static_backdrop=True)

Practical Functionality

1. ConfirmDialog (Preset)

FastStrap provides a specialized ConfirmDialog for standard "Are you sure?" scenarios. It simplifies the API by pre-configuring the "Yes/No" buttons.

from faststrap import ConfirmDialog

ConfirmDialog(
    "Delete this post? This cannot be undone.",
    title="Confirm Deletion",
    dialog_id="confirmDelete",
    confirm_text="Yes, Delete It",
    variant="danger",
    hx_delete="/post/1", # Action on confirm
    hx_target="#post-1"
)

`faststrap.components.feedback.confirm.ConfirmDialog(message, *, confirm_text='Confirm', cancel_text='Cancel', title='Confirm Action', variant='danger', dialog_id=None, hx_confirm_method='post', hx_confirm_url=None, hx_target=None, hx_swap=None, **kwargs)`

Bootstrap Confirmation Dialog (pre-configured Modal).

A modal designed for confirming destructive actions.

Parameters:

Name	Type	Description	Default
`message`	`str \| Any`	Body text	required
`confirm_text`	`str`	Text for confirm button	`'Confirm'`
`cancel_text`	`str`	Text for cancel button	`'Cancel'`
`title`	`str`	Modal title	`'Confirm Action'`
`variant`	`VariantType`	Variant for confirm button (danger, primary, etc.)	`'danger'`
`dialog_id`	`str \| None`	ID for the modal	`None`
`hx_confirm_method`	`str`	HTMX method for confirm button (post, delete, put, get)	`'post'`
`hx_confirm_url`	`str \| None`	URL to call on confirmation	`None`
`hx_target`	`str \| None`	HTMX target	`None`
`hx_swap`	`str \| None`	HTMX swap strategy	`None`
`**kwargs`	`Any`	Additional HTML attributes passed to Modal	`{}`

Returns:

Type	Description
`Div`	Modal component

Examples:

>>> ConfirmDialog(
...     "Are you sure you want to delete this?",
...     hx_confirm_url="/delete/1",
...     confirm_text="Delete",
...     variant="danger"
... )

2. ConfirmAction (HTMX Prompt)

Use ConfirmAction when a browser confirmation prompt is enough and a full modal would be too heavy.

from faststrap import ConfirmAction

ConfirmAction(
    "Archive",
    url="/items/1/archive",
    method="delete",
    confirm="Archive this item?",
    target="#items",
    swap="outerHTML",
)

This renders a themed Button with hx-confirm plus the selected HTMX method attribute.

`faststrap.components.feedback.confirm.ConfirmAction(*children, url, confirm='Are you sure?', method='post', target=None, swap=None, variant='danger', **kwargs)`

HTMX-friendly action button with a browser confirmation prompt.

Use this when a full modal is too heavy and the action can be confirmed with HTMX's built-in hx-confirm behavior.

3. Real-time Loading

You can put HTMX content inside a modal body to load data only when opened.

Modal(
    Div(hx_get="/api/user_details", hx_trigger="intersect once"), # Loads when modal opens
    title="User Profile",
    modal_id="profileModal"
)

Focus Trap (Accessibility)

Trap keyboard focus inside the modal and optionally set autofocus:

Modal(
    "Secure content",
    title="Accessible Dialog",
    focus_trap=True,
    autofocus_selector="#first-field",
)

Parameter Reference

FastStrap Param	Type	Bootstrap Attribute	Description
`title`	`str`	`.modal-title`	Text for the top header.
`footer`	`Any`	`.modal-footer`	Elements to put in bottom row.
`size`	`str`	`.modal-{size}`	`sm`, `lg`, `xl`, `fullscreen`.
`centered`	`bool`	`.modal-dialog-centered`	Vertically centers the dialog.
`scrollable`	`bool`	`.modal-dialog-scrollable`	Makes body scrollable independently.
`static_backdrop`	`bool`	`data-bs-backdrop`	`static` prevents click-to-close.
`keyboard`	`bool`	`data-bs-keyboard`	If `False`, Escape key won't close it.
`focus_trap`	`bool`	Focus trap helper	Keeps keyboard focus inside the modal while it is open.
`autofocus_selector`	`str`	Focus trap helper	CSS selector for the element to focus when the modal opens.

`faststrap.components.feedback.modal.Modal(*children, modal_id=None, title=None, footer=None, size=UNSET, centered=UNSET, scrollable=UNSET, fullscreen=UNSET, static_backdrop=UNSET, fade=UNSET, focus_trap=UNSET, autofocus_selector=UNSET, dialog_cls=UNSET, content_cls=UNSET, header_cls=UNSET, body_cls=UNSET, footer_cls=UNSET, title_cls=UNSET, close_cls=UNSET, **kwargs)`

Bootstrap Modal component for dialog boxes and overlays.

Parameters:

Name	Type	Description	Default
`*children`	`Any`	Modal body content	`()`
`modal_id`	`str \| None`	Unique ID for the modal (required for Bootstrap JS)	`None`
`title`	`str \| None`	Modal header title	`None`
`footer`	`Any \| None`	Modal footer content	`None`
`size`	`ModalSizeType \| None`	Modal size (sm, lg, xl)	`UNSET`
`centered`	`bool \| None`	Vertically center modal	`UNSET`
`scrollable`	`bool \| None`	Make modal body scrollable	`UNSET`
`fullscreen`	`bool \| Literal['sm-down', 'md-down', 'lg-down', 'xl-down', 'xxl-down'] \| None`	Full-screen modal	`UNSET`
`static_backdrop`	`bool \| None`	Clicking backdrop doesn't close modal	`UNSET`
`fade`	`bool \| None`	Use fade animation	`UNSET`
`focus_trap`	`bool \| None`	Trap keyboard focus inside the modal	`UNSET`
`autofocus_selector`	`str \| None`	CSS selector for the element to autofocus	`UNSET`
`**kwargs`	`Any`	Additional HTML attributes (cls, hx-, data-, etc.)	`{}`