---
title: Tooltip
url: "https://native-sdk.dev/docs/components/tooltip"
docs_index: /llms.txt
lastUpdated: 2026-10-16
---

> For an index of all documentation, see [/llms.txt](/llms.txt).

Use `tooltip` to annotate a control. It is a text leaf with model interpolation. Place it beside a trigger in a `stack` and set `anchor="above"` or `anchor="below"`. The runtime manages visibility on hover and keyboard focus; no model hover state is required. Without an anchor, the tooltip is ordinary static content. For a chat-message surface, see [bubble](/docs/components/bubble).

## Markup

```html
<stack>
  <button variant="outline" on-press="toggle_bold">Bold</button>
  <tooltip anchor="above">Bold the selection</tooltip>
</stack>
```

## Hover intent

An anchored tooltip appears after `tooltip-delay` milliseconds of pointer hover (default 600). Set the delay to `0` for immediate display. After the pointer leaves a shown tooltip, a shared 400 ms window allows the next trigger’s tooltip to appear immediately. Theme metric tokens `tooltip_show_delay_ms` and `tooltip_warm_window_ms` control these defaults.

The tooltip stays open while the pointer is over the trigger, the tooltip, or the gap between them. Scrolling updates hit testing: moving a trigger out from under the pointer hides or cancels its tooltip; bringing one under the pointer starts the delay.

Keyboard focus shows the tooltip immediately. Moving focus away or pressing Escape hides it without opening the pointer warm window. Any pointer-down or Space/Enter activation cancels pending display, hides the tooltip, and clears that window. Losing view or window focus clears tooltip state.

Without `anchor`, the element displays whenever it is present in the view. Use a model-bound `if` to control that form.

## Programmatic construction (Zig)

In a Zig view, the `canvas.Ui` builder constructs the same tree programmatically:

```zig
ui.el(.stack, .{}, .{
    ui.button(.{ .variant = .outline, .on_press = .toggle_bold }, "Bold"),
    ui.el(.tooltip, .{ .text = "Bold the selection", .anchor = .above }, .{}),
})
```

## Attributes

| Attribute          | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `text`             | Text value for text-bearing elements; a literal or one \{binding}.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `anchor`           | dropdown-menu and tooltip: floats the surface against its PARENT's frame instead of the flow (literal below or above; either side auto-flips at the window edges). Late z-pass above the whole tree, window-clipped — never cropped by a scroll pane, never reflows siblings. Put the surface beside its trigger inside a stack. An anchored tooltip's visibility is runtime-owned (hover intent on the trigger; see tooltip-delay), unlike the model-owned dropdown.                                                                                                              |
| `anchor-alignment` | dropdown-menu and tooltip (with anchor): horizontal alignment against the anchor - start, end, or stretch (stretch also widens the surface to at least the anchor's width, the select-menu look).                                                                                                                                                                                                                                                                                                                                                                                  |
| `anchor-offset`    | dropdown-menu and tooltip (with anchor): literal gap in points between the anchor edge and the surface (default 4).                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `tooltip-delay`    | tooltip only, beside anchor: hover-intent show delay in milliseconds (a plain number or one \{binding}) - the runtime shows the anchored tooltip after its trigger has been hovered this long on the recorded frame clock. 0 shows the instant the trigger is hovered; absent follows the 600ms token default. A shared 400ms warm window after a pointer-hovered tooltip hides on leave skips the delay on the next trigger (no other hide cause warms); keyboard-focus reveals are always immediate. A delay without an anchor is a teaching error (it would be silently inert). |

---

For a semantic overview of all documentation, see [/sitemap.md](/sitemap.md)

For an index of all available documentation, see [/llms.txt](/llms.txt)

For agent-facing discovery, including API and MCP surfaces, see [/agents.md](/agents.md)