# Tooltip

> A hint shown on hover, optionally with its shortcut. A native Pyzed component for Python desktop GUIs, with a live preview, code examples and its API.

Source: https://albakore.github.io/pyzed/library/tooltip/

:::tip[In plain words]
A little box with a hint that appears when you rest the mouse on something.
:::

Wraps any widget and shows a small themed box next to it while the mouse is over it. `keys=` adds the shortcut and `position` is `"top"`, `"bottom"` (default), `"left"` or `"right"`. `pz.tooltip` is the unstyled base version.

`ui.tooltip` · Category: [Display](https://albakore.github.io/pyzed/library/#display) · [Full reference →](https://albakore.github.io/pyzed/reference/ui/#tooltip)

**Code:**

```python
pz.row([
    ui.tooltip(ui.icon_button("save", on_save), "Save", keys="ctrl-s"),
    ui.icon_button("settings", on_settings, tooltip="Settings"),
], spacing=8)
```

## When to use

- On icon buttons and compact controls whose meaning is not obvious.
- Don't hide essential information in a tooltip: it is invisible on touch and keyboard use.

## Usage

```python
import pyzed as pz
from pyzed import ui

pz.row([
    ui.tooltip(ui.icon_button("save", on_save), "Save", keys="ctrl-s"),
    ui.icon_button("settings", on_settings, tooltip="Settings"),
], spacing=8)
```

## Variants

:::note[About these captures]
Each capture is recorded by pyzed itself, off-screen at 2x, in One Dark or One Light to match this site's theme, and cropped to the component so it shows at its real size. The pointer hovers, presses or types into it; a component that does not react to the pointer cycles through a few themes. With reduced motion you see the first frame. Open **Code** under a capture to see the snippet that draws it; free names such as `on_save` stand for your own callbacks.
:::

### Position

Drawn as the pointer shows it: tooltips only open on hover.

```python
ui.tooltip(ui.icon_button("save", on_save), "Save")
```

```python
ui.tooltip(ui.icon_button("save", on_save), "Save", position="top")
```

```python
ui.tooltip(ui.icon_button("save", on_save), "Save", position="right")
```

```python
ui.tooltip(ui.icon_button("save", on_save), "Save", position="left")
```

### Content

Drawn as the pointer shows it: tooltips only open on hover.

```python
ui.tooltip(ui.button("Save", on_save), "Save the file", keys="ctrl-s")
```

```python
ui.icon_button("settings", on_settings, tooltip="Settings")
```

## Events

Tooltip has no events of its own: it shows what you give it. Like every widget it also has the **18 common events** (`click`, `double_click`, `right_click`, `mouse_enter`, `drag`, `key_down`, `resize`…), attached with `.on(...)`: see [Events](https://albakore.github.io/pyzed/guides/events/) and [Events of every component](https://albakore.github.io/pyzed/library/events/).

## Tips

:::tip
Tooltips only appear on hover, so the preview shows the buttons. `ui.icon_button(..., tooltip="Text")` is a shortcut for wrapping it in `ui.tooltip`.
:::

## Properties and API

### `ui.tooltip`

```python
tooltip(content, text, *, keys=None, position='bottom', theme=None)
```

Wraps `content` with a themed tooltip, optionally with its shortcut.

| Property | Default | Description |
| --- | --- | --- |
| `content` | *required* | Content: a `Widget`, a string or a number (converted to text). |
| `text` | *required* | Tooltip text. |
| `keys` | `None` | Shortcut shown at the end, written as a string: `"ctrl-s"`, `"cmd-k cmd-s"`. |
| `position` | `"bottom"` | `"top"`, `"bottom"`, `"left"`, `"right"` or `"cursor"`. |
| `theme` | `None` | Theme to use instead of the current one (`pyzed.theme.current()`). |

[Full reference →](https://albakore.github.io/pyzed/reference/ui/#tooltip)

### `pz.tooltip`

```python
tooltip(
    content,
    tip,
    *,
    position='bottom',
    gap=4.0,
    bg=None,
    color=None,
    border_color=None,
    border_width=0.0,
    radius=None,
    shadow=None,
)
```

Shows `tip` next to `content` on hover. `ui.tooltip` adds the theme's style.

| Property | Default | Description |
| --- | --- | --- |
| `content` | *required* | Content: a `Widget`, a string or a number (converted to text). |
| `tip` | *required* | Tooltip content. |
| `position` | `"bottom"` | `"top"`, `"bottom"`, `"left"`, `"right"` or `"cursor"`. |
| `gap` | `4.0` | Distance from the content. |
| `bg` | `None` | Background color (`"#rrggbb[aa]"`, `(r, g, b[, a])` or `"transparent"`). |
| `color` | `None` | Text or icon color. |
| `border_color` | `None` | Border color. |
| `border_width` | `0.0` | Border width in pixels. |
| `radius` | `None` | Corner radius: a number or `(top_left, top_right, bottom_right, bottom_left)`. |
| `shadow` | `None` | Shadow: `(color, (dx, dy), blur)`. |

[Full reference →](https://albakore.github.io/pyzed/reference/widgets/#tooltip)

## Related

- [Icon button](https://albakore.github.io/pyzed/library/icon-button/): A square button with just an icon and an optional tooltip.
- [Kbd](https://albakore.github.io/pyzed/library/kbd/): Keyboard shortcuts drawn as keys, with symbols on macOS.
- [Popover](https://albakore.github.io/pyzed/library/popover/): Floating content at a point: context menus, color pickers.