Tooltip

A small popup that appears when the mouse hovers over a widget. Tooltips can follow the mouse or anchor to a specific edge of the target.

Usage

A tooltip is an attachment, not a placed widget: create it once on a target and it manages its own hover, show, and hide. Keep a reference only if you want to update its text or destroy() it later. Positioning follows the mouse by default, or pins to an edge of the target with anchor_point.

Basic

Pass any bootstack widget as the first argument followed by text. The tooltip appears after 250 ms on hover and hides on mouse leave or click.

btn = bs.Button("Save")
bs.Tooltip(btn, "Save your changes to disk")

Covering a container

When the target is a container, the tooltip shows while the pointer is anywhere inside it — including over its children. This covers the children that exist when the tooltip is created.

with bs.Card(gap=8) as card:
    bs.Label("Disk usage")
    bs.Label("82% full")
bs.Tooltip(card, "Hover anywhere on the card")

Add children to the container after creating the tooltip and they are not covered automatically. Call refresh_bindings() to extend coverage to them — it is safe to call repeatedly.

tip = bs.Tooltip(card, "Hover anywhere on the card")
bs.Label("3.2 GB free", parent=card)   # added later
tip.refresh_bindings()                 # now covered too

Anchor positioning

By default the tooltip follows the mouse. Pass anchor_point to pin the tooltip to a specific edge of the target widget. window_point sets which edge of the tooltip aligns to the anchor — when omitted it defaults to the opposite of anchor_point.

btn = bs.Button("More info")

# Above the button
bs.Tooltip(btn, "Anchored above", anchor_point="n", window_point="s")

# Below the button
bs.Tooltip(btn, "Anchored below", anchor_point="s", window_point="n")

# To the right
bs.Tooltip(btn, "Anchored right", anchor_point="e", window_point="w")

Accent colors

Color-code tooltips by intent with accent=.

bs.Tooltip(btn_p, "Primary tooltip", accent="primary")
bs.Tooltip(btn_s, "Success tooltip", accent="success")
bs.Tooltip(btn_w, "Warning tooltip", accent="warning")
bs.Tooltip(btn_d, "Danger tooltip",  accent="danger")

Text wrapping and alignment

Set wrap_width (pixels) to limit line length. Use justify= to control alignment inside the tooltip.

bs.Tooltip(
    btn,
    "This tooltip has a longer explanation that wraps to multiple lines.",
    wrap_width=220,
)

bs.Tooltip(btn, "Centered\ntooltip text", justify="center")

Hover delay

Adjust the delay with delay (milliseconds). Pass 0 for instant display.

bs.Tooltip(btn, "Appears instantly", delay=0)
bs.Tooltip(btn, "Appears after one second", delay=1000)

Auto-flip

By default (auto_flip=True) the tooltip flips axes to stay fully on screen. Pass 'vertical' or 'horizontal' to restrict flipping to one axis, or False to disable it entirely.

bs.Tooltip(btn, "Never flips", auto_flip=False)
bs.Tooltip(btn, "Flips vertically only", auto_flip="vertical")

Updating the text

text is a live property. Keep a reference to the tooltip and assign a new value to change it — a visible tooltip updates immediately, and the next hover shows the new text.

tip = bs.Tooltip(save_btn, "Not saved")
# … after saving …
tip.text = "All changes saved"

Removing a tooltip

Call destroy() to remove the tooltip and unbind all event handlers from the target widget.

tip = bs.Tooltip(btn, "Temporary help text")
# … later …
tip.destroy()

See also

ContextMenu — a popup attached to a widget, opened on right-click rather than hover.

Toasts & Notifications — transient corner notifications for status and feedback.

API

The complete reference for Tooltip lives on the Widgets API page. At a glance:

Tooltip

A hover tooltip attached to a target widget.

Full Example

with bs.App(title="Tooltip", size=(660, 440), padding=20, gap=14) as app:

    bs.Label("Basic", font="heading-md")
    with bs.Row(gap=8):
        b1 = bs.Button("Hover me")
        bs.Tooltip(b1, "This is a helpful tooltip.")

        b2 = bs.Button("Instant")
        bs.Tooltip(b2, "Appears immediately.", delay=0)

        b3 = bs.Button("Slow (1 s)")
        bs.Tooltip(b3, "Appears after a 1-second delay.", delay=1000)

    bs.Label("Accent colors", font="heading-md")
    with bs.Row(gap=8):
        b4 = bs.Button("Default")
        bs.Tooltip(b4, "Default accent")

        b5 = bs.Button("Primary")
        bs.Tooltip(b5, "Primary accent", accent="primary")

        b6 = bs.Button("Info")
        bs.Tooltip(b6, "Info accent", accent="info")

        b7 = bs.Button("Success")
        bs.Tooltip(b7, "Success accent", accent="success")

        b8 = bs.Button("Warning")
        bs.Tooltip(b8, "Warning accent", accent="warning")

        b9 = bs.Button("Danger")
        bs.Tooltip(b9, "Danger accent", accent="danger")

    bs.Label("Anchored positioning", font="heading-md")
    with bs.Row(gap=8):
        b10 = bs.Button("Above")
        bs.Tooltip(b10, "Anchored above the button",
                   anchor_point="n", window_point="s")

        b11 = bs.Button("Below")
        bs.Tooltip(b11, "Anchored below the button",
                   anchor_point="s", window_point="n")

        b12 = bs.Button("Right")
        bs.Tooltip(b12, "Anchored to the right",
                   anchor_point="e", window_point="w")

        b13 = bs.Button("Left")
        bs.Tooltip(b13, "Anchored to the left",
                   anchor_point="w", window_point="e")

    bs.Label("Text wrapping and alignment", font="heading-md")
    with bs.Row(gap=8):
        b14 = bs.Button("Wrapped text")
        bs.Tooltip(
            b14,
            "This tooltip has a longer explanation that wraps across multiple lines.",
            wrap_width=200,
        )

        b15 = bs.Button("Center aligned")
        bs.Tooltip(
            b15,
            "Centered\ntooltip text",
            justify="center",
            wrap_width=180,
        )

app.run()