Tooltip
A tooltip is a short text bubble that shows when people hover over or focus a control. It never holds anything people need.
<tk-tooltip text="Also removes the file from shared folders"> <tk-button tone="danger">Delete</tk-button> </tk-tooltip>
Anatomy
| Part | What it is |
|---|---|
tk-tooltip |
the wrapper |
| default slot | one control that can take focus: the trigger |
| bubble | the text, shown in the top layer, 4px from the trigger; no arrow |
Types
<tk-tooltip type="label"> <tk-icon-button label="Copy link"><tk-icon name="copy"></tk-icon></tk-icon-button> </tk-tooltip> <tk-tooltip text="Shared with 3 people"> <tk-button>Share</tk-button> </tk-tooltip>
Both look the same; they differ in what screen readers hear.
label: the text is the control's name. Use it only on icon-only controls. With atk-icon-button, leavetextout: the tooltip shows the button'slabel, so the two always match.description(default): the text adds to the control's name. Don't repeat the visible label.
Placement
<tk-tooltip text="Moves the item to the top" placement="top"> <tk-button>Pin</tk-button> </tk-tooltip> <tk-tooltip text="Moves the item to the end" placement="end"> <tk-button>Archive</tk-button> </tk-tooltip>
placementis the preferred side:top,bottom(default),start, orend.startandendfollow the text direction.- When there's no room, the bubble moves to the opposite side and stays inside the viewport. Change the side only to keep something important uncovered.
Showing and hiding
- Hover shows the bubble after 400ms; keyboard focus shows it at once.
- It stays while the pointer is on the trigger or the bubble, and never times out.
Eschides it and focus stays on the trigger.- It shows and hides instantly, with no animation.
- A tap opens nothing: it activates the control. Keep essential information out of the tooltip, so a touch user loses nothing.
When to use
- Show the name of an icon-only button, with
type="label". - Add one short note to a control that already has a name, with
type="description"(the default). - Try something else first. Put lasting notes in helper text or on the page, and don't repeat the words already on the control. Anything people must read to succeed doesn't belong in a tooltip.
- Use a
Popover for links, buttons, or longer content. A tooltip holds plain text only. - Only on controls people can focus. Never on plain text.
Content
- Label: name the action in one or two words, the same words as the button's
label: "Rename", "Copy link". - Description: one short sentence that adds something, with the useful word first.
- Use sentence case and a calm tone. Never an error, a security notice, or a step people need to finish the task.
- Keep it short. The bubble wraps at 280px.
More in
Do / Don't
| ✅ Do | ❌ Don't |
|---|---|
Use label to show an icon-only button's name |
Put a label tooltip on a control with visible text |
| Add a short note the label can't fit | Repeat the visible label as a description |
| Put lasting information on the page | Hide something people need in a bubble |
| Wrap a button, link, or field | Wrap plain text or a bare div |
Keep the default bottom |
Pick a side without a reason |
Related
Icon button : the main partner of alabeltooltip.Popover : a panel with links, buttons, or more text.Button : the usual trigger for a description.
API
Attributes
| Attribute | Type | Default | What it does |
|---|---|---|---|
text |
string | none | the text; required, except for type="label" on a tk-icon-button |
type |
description | label |
description |
adds to the trigger's name, or becomes it |
placement |
top | bottom | start | end |
bottom |
the preferred side |
Slots
| Slot | Content |
|---|---|
| default | one control that can take focus |
Events
No events.
Tokens
| Part | Tokens |
|---|---|
| bubble | surface/inverse, shadow-2, radius-8; in high contrast, a 1px border/default |
| text | text/inverse, Caption (12/16) |
| padding | space-8 inline, space-4 block |
| gap to the trigger | space-4 |
Values per theme:
Accessibility
Built in:
- The bubble is hidden from screen readers. The text is read from a hidden copy linked to
the trigger: as its description, or as its name with
type="label". - Hover and focus both show it;
Eschides it without moving focus, and only the tooltip closes, not a dialog around it. - The pointer can move onto the bubble without it closing, and it never times out.
- Nothing in the bubble takes focus.
- A console warning flags a trigger that can't take focus.
Your part:
- Keep it non-essential. Touch users may never see it.
- Wrap a control that can take focus, never plain text.
- Don't use the
titleattribute instead; keyboard and touch users never see it.
| Key | Action |
|---|---|
Tab |
focuses the trigger and shows the tooltip |
Esc |
hides the tooltip; focus stays on the trigger |
Known limits
- A
descriptionon a Thykes control isn't read yet. Ontk-button,tk-icon-button,tk-link, and othertk-*triggers, screen readers don't hear the description; on a native<button>or<a>they do. Don't rely on it for anything people need. type="label"names only atk-icon-buttonor a native control. Use atk-icon-buttonwith alabelfor icon-only actions.