---
name: tooltip-usage
description: >
Use after component-usage-ux when an app needs @techsio/ui-kit Tooltip for
supplemental hover/focus help using the Zag.js tooltip wrapper, supported
timing, placement, interaction, controlled state, and token styling props.
metadata:
component_version: "2.0.0"
type: "core"
library: "@techsio/ui-kit"
library_version: "0.3.2"
requires: "component-usage-ux app-token-overrides ux-guidelines"
resources: "references/ux.md ../../references/component-contracts.md ../../references/consumer_app_usage_rules.md"
sources: "https://zagjs.com/components/react/tooltip"
contributor_sources: "libs/ui/src/atoms/tooltip.tsx libs/ui/src/tokens/components/atoms/_tooltip.css libs/ui/stories/atoms/tooltip.stories.tsx libs/ui/src/atoms/tooltip.figma.ts"
audience: "consumer"
---
> Portable scope: Use the installed package's exported types and bundled sibling skills. Repository source paths are optional contributor evidence, not consumer prerequisites; use the consuming app's own checks. Resolve ../../references/ paths from this skill's folder, not the app working directory.
# @techsio/ui-kit Tooltip Usage
Use Tooltip for short supplemental information on hover/focus. Do not use it
for required instructions, blocking errors, or primary content.
## UX/UI guidelines
House rules come from the `ux-guidelines` skill (writing, formatting, states,
where actions and feedback live). This section applies them to `Tooltip`.
**Use it when**
- Short, non-essential hints on hover and focus: icon-button names, truncated text, keyboard shortcuts.
**Use something else when**
| Need | Use instead |
| --- | --- |
| Required information or instructions | visible help text |
| Interactive content | Popover |
| Errors | inline StatusText / field error |
**Do**
- Keep to a few words; repeat the ActionIcon's `aria-label`.
- Attach to focusable triggers so keyboard users get it too.
- Use for the full value of truncated cells.
**Don't**
- Put tooltips on disabled buttons (they don't receive hover/focus) — explain next to the control.
- Put links or buttons inside a tooltip.
- Use tooltips on touch-only surfaces as the only explanation.
**Copy and states**
- No trailing period for fragments; sentence case.
**Behaviour (from the UX spec)**
- The task must make sense without the hint, including on touch screens where there is no hover.
- The bubble stays open while the pointer moves onto it (`interactive`, default) and Escape closes it without moving focus.
- Never the only place for a format or instruction a field needs; show that as help text.
**Figma → code**
| Figma | Code |
| --- | --- |
| `placement=…` (8 values) | `placement` (any Zag placement; flips on collision) |
| `Tooltip/md/default/right-start` frame | `size="md" appearance="solid" placement="right-start"` |
Full UX page (anatomy, states, behaviour, edge cases): [references/ux.md](references/ux.md). The same page renders in Storybook as *Atoms/Tooltip → UX guidelines*.
## Setup
```tsx
import { ActionIcon } from "@techsio/ui-kit/atoms/action-icon"
import { Tooltip } from "@techsio/ui-kit/atoms/tooltip"