Popover¶

Popover is a small overlay with optional header and body text, anchored to a target control. It is the library mapping of Bootstrap 5 popover, used for richer hints than a Tooltip: short explanations, confirmations, and extra fields that should not navigate away.

Use a Popover when the extra copy needs structure (a title plus a body) or a click trigger. Use a Tooltip when a single phrase on hover or focus is enough.

Basic usage¶

popover_basic_usage example

def demo() -> None:
    with bs.scope():
        button = ui.button("Status")
        bs.popover(
            bs.PopoverHeader("Publish state"),
            bs.PopoverBody("This record is ready to publish."),
            target=button,
            placement="bottom",
            trigger="click",
        )

Compose the overlay with PopoverHeader and PopoverBody children. The popover is not laid out in the button's parent; it is mounted on the shared overlay root (portal) so it can escape overflow and stacking contexts.

Options¶

Header and body composition¶

Pass a PopoverHeader for the title row and a PopoverBody for the main copy. Either piece can be omitted when you only need one of them, but the pair is the usual pattern because it matches the Bootstrap popover anatomy readers already know.

popover_header_body example

def demo() -> None:
    with bs.scope():
        link = ui.link("Policy")
        bs.popover(
            bs.PopoverHeader("Retention"),
            bs.PopoverBody("Logs are kept for 30 days."),
            target=link,
            placement="right",
            trigger="click",
        )

Keep the body short. If the content needs a form or a long list, an Offcanvas or a modal is a better host.

Target¶

target accepts either a public id string or an element reference. Passing the widget you just created is the straightforward path. Passing a public id is useful when the trigger is declared elsewhere in the page and you only have its id at composition time.

popover_target_id example

def demo() -> None:
    with bs.scope():
        ui.button("Details").props("id=details-trigger")
        bs.popover(
            bs.PopoverBody("More information"),
            target="details-trigger",
            placement="top",
            trigger="click",
        )

The overlay always lives in the shared overlay portal, not inside the target. Do not try to position it with parent-relative CSS; placement is the supported hook.

Placement¶

placement is the preferred side of the target: top, bottom, left, right, and the Bootstrap start/end variants. The popover may flip if there is not enough space. Pick the side that does not cover the control the user just used.

Trigger¶

trigger chooses the gesture that opens the overlay. click is the default for popovers because the content is richer than a tooltip. hover and focus are available when the copy is a hint rather than an action. Avoid hover-only triggers on touch-first pages.

Argument reference¶

Property	Type	Default	DBC 2.0.4 name	Support (native)	Support (compat)
children	a list of or a singular dash component, string or number	None	children	supported	supported
id	string	None	id	supported	supported
target	string \| dict	None	target	supported	supported
is_open	boolean	None	isOpen	supported	supported
trigger	string	None	trigger	supported	supported
placement	a value equal to: 'auto', 'auto-start', 'auto-end', 'top', 'top-start', 'top-end', 'right', 'right-start', 'right-end', 'bottom', 'bottom-start', 'bottom-end', 'left', 'left-start', 'left-end'	'right'	placement	supported	supported
hide_arrow	boolean	None	hideArrow	supported	supported
delay	dict	{show: 0, hide: 50}	delay	supported	supported
offset	string \| number	None	offset	supported	supported
flip	boolean	True	flip	supported	supported
body	boolean	None	body	supported	supported
autohide	boolean	False	autohide	supported	supported
style	unknown	None	style	supported	supported
class_name	string	None	className	supported	supported
persistence	boolean \| string \| number	None	persistence	unsupported	unsupported
persisted_props	list of a value equal to: 'is_open's	None	persisted_props	unsupported	unsupported
persistence_type	a value equal to: 'local', 'session', 'memory'	None	persistence_type	unsupported	unsupported
key	string	None	key	unsupported	unsupported
class_name	string	None	className	supported	supported