⚠️ Important! Project Has MovedThis project has been incorperated into the NenoTk library.
Please use and contribute to that repository instead — this repo may be out of date and will not receive updates or support.
Bind tooltips to any widget that inherits from tkinter.Widget, including custom widgets.
-
Install from the repository:
pip install git+https://github.com/Nenotriple/TkToolTip.git@main
-
Import in your Python script:
from TkToolTip import TkToolTip as Tip
Warning
v1.12+ introduces breaking changes to the API.
For legacy support use git+https://github.com/Nenotriple/[email protected]
Tooltips must be associated with a widget. There are two common patterns.
Tip.bind(widget, text="example")tooltip = Tip.bind(widget, text="example")
tooltip.config(text="Example!")- Lightweight binding API: attach a tooltip with
Tip.bind(widget, ...). - Works with any
tkinter.Widget, including custom widgets. - Live reconfiguration via
tooltip.config(...)for text, style, timing, and behavior. - Positioning options:
origin(mouseorwidget) andanchor(nine positions). - Optional
follow_mousemode to track the cursor while hovering. - Appearance controls: background, foreground,
font,borderwidth,relief,justify, padding. - Wrapping support via
wraplengthand adjustable padding (padx,pady,ipadx,ipady). - Timing controls:
show_delay,hide_delay, and auto-hide behavior. - Animations:
fade,slide, ornonewith adjustableanim_inandanim_out. - Opacity control (0.0–1.0) for translucent tooltips.
- Respects screen bounds and avoids mouse overlap when positioned from the pointer.
| Parameter | Type | Default | Possible Values | Description |
|---|---|---|---|---|
widget |
tkinter.Widget |
— | Any Tkinter widget | The widget to which the tooltip will be attached. |
text |
str |
"" |
Any string | The content displayed inside the tooltip. |
state |
str |
"normal" |
"normal", "disabled" |
Controls whether the tooltip is active. |
bg |
str |
"#ffffee" |
Valid color name / hex | Tooltip background color. |
fg |
str |
"black" |
Valid color name / hex | Text color used in the tooltip. |
font |
tuple |
("TkDefaultFont", 8, "normal") |
(family, size, style) |
Font settings for the tooltip text. |
borderwidth |
int |
1 |
Any integer ≥ 0 | Thickness of the tooltip border. |
opacity |
float |
1.0 |
0.0 to 1.0 |
Tooltip transparency (0.0 = transparent, 1.0 = opaque). |
relief |
str |
"solid" |
"solid", "raised", "sunken", "ridge", "groove", "flat" |
Style of the tooltip border. |
justify |
str |
"center" |
"left", "center", "right" |
Alignment of the tooltip text. |
wraplength |
int |
0 |
Any integer ≥ 0 | Max width (px) before wrapping. 0 disables wrapping. |
padx |
int |
1 |
Any integer | Horizontal offset of the tooltip from its origin. |
pady |
int |
1 |
Any integer | Vertical offset of the tooltip from its origin. |
ipadx |
int |
2 |
Any integer | Additional horizontal padding inside the tooltip. |
ipady |
int |
2 |
Any integer | Additional vertical padding inside the tooltip. |
origin |
str |
"mouse" |
"mouse", "widget" |
Reference point for positioning the tooltip. |
anchor |
str |
"nw" |
"n", "ne", "e", "se", "s", "sw", "w", "nw", "center", "c", "nesw" |
Position relative to widget when using widget origin. |
follow_mouse |
bool |
False |
True, False |
If True, the tooltip follows the mouse while hovering. |
show_delay |
int |
100 |
Any integer ≥ 0 | Milliseconds to wait before showing after hover. |
hide_delay |
int |
5000 |
Any integer ≥ 0 | Milliseconds before the tooltip automatically hides. |
animation |
str |
"fade" |
"fade", "slide", "none" |
Animation style for showing / hiding. |
anim_in |
int |
75 |
Any integer ≥ 0 | Duration (ms) of the show (enter) animation. |
anim_out |
int |
50 |
Any integer ≥ 0 | Duration (ms) of the hide (exit) animation. |
Set animation to control how the tooltip appears and disappears:
fade(default): cross-fade opacity from 0 →opacity.slide: slides upward a few pixels while fading in; reverses when hiding.none: instantly shows and hides with no transitions.
Use anim_in and anim_out to tune durations (milliseconds).
TkToolTip/
TkToolTip.py # Tooltip implementation
position_utils.py # Position calculations
animation_utils.py # Animation logic
TkToolTip.pyi # Type stubs for IDEs / type checking
examples/
demo.py # Comprehensive GUI demo
MIT License. See LICENSE for details.