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

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")

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, "Required field", accent="danger")
bs.Tooltip(btn, "Saved successfully", accent="success")
bs.Tooltip(btn, "New in this release", accent="info")

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")

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()

Widget sizing

All widgets accept self-placement kwargs via **kwargs. The parent container determines which options apply — stack-based parents use stack kwargs, grid-based parents use grid kwargs. Unrecognised keys are silently ignored.

Stack

Used inside VStack, HStack, App, and other stack containers.

fill	Fill direction: 'x', 'y', 'both', or 'none'.
expand	Grow to consume extra space in the parent. True or False.
anchor	Alignment when the widget does not fill the available slot: 'n', 's', 'e', 'w', 'center', 'nw', etc.
margin	External spacing in pixels. Accepts an integer (equal on all sides), a 2-tuple (horizontal, vertical), or a 4-tuple (left, top, right, bottom).
margin_x	Horizontal external spacing (left and right). Accepts an integer or a 2-tuple (left, right) for asymmetric spacing. Overrides the horizontal component of margin=.
margin_y	Vertical external spacing (top and bottom). Accepts an integer or a 2-tuple (top, bottom) for asymmetric spacing. Overrides the vertical component of margin=.

Grid

Used inside a Grid container.

row / column	Zero-based row and column indices.
rowspan / columnspan	Number of rows or columns to span.
sticky	Alignment and fill within the grid cell. Any combination of 'n', 's', 'e', 'w' — e.g. 'ew' stretches horizontally, 'nsew' fills the entire cell.
margin	External spacing in pixels. Accepts an integer, a 2-tuple (horizontal, vertical), or a 4-tuple (left, top, right, bottom).
margin_x	Horizontal external spacing. Accepts an integer or (left, right).
margin_y	Vertical external spacing. Accepts an integer or (top, bottom).

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.HStack(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.HStack(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.HStack(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.HStack(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()