Tooltip
Displays a brief visual label when a trigger receives hover or focus.
Design
Functional preview
Running with the stable ds-tis/tooltip JavaScript runtime.
Loading functional preview…
Open the HTML/CSS/JS playground
Anatomy
Edit document
2
3
4
1 Trigger — the element that activates the tooltip on hover/focus.
2 Tooltip container (
3 Arrow — CSS pseudo-element pointing toward the trigger.
4 Content — text only, no interactive elements.
2 Tooltip container (
.ds-tooltip) — dark background, positioned relative to trigger.3 Arrow — CSS pseudo-element pointing toward the trigger.
4 Content — text only, no interactive elements.
Positions
The tooltip content appears on the specified side of the trigger. The arrow (via ::before) points toward the trigger element.
Tooltip on top
Tooltip on bottom
Tooltip on left
Tooltip on right
With icon buttons
Tooltips are especially useful on icon-only buttons to clarify their purpose.
Edit
Delete
Token mapping
| Property | Token | CSS variable |
|---|---|---|
| background | semantic.background.inverse | --ds-background-inverse |
| text | semantic.brand.content.default | --ds-brand-content-default |
| padding-x | component.tooltip.content.padding-x.default | --ds-tooltip-content-padding-x-default |
| padding-y | component.tooltip.content.padding-y.default | --ds-tooltip-content-padding-y-default |
| border-radius | component.tooltip.content.radius.default | --ds-tooltip-content-radius-default |
| label font-size | component.tooltip.label.font-size.default | --ds-tooltip-label-font-size-default |
| label line-height | component.tooltip.label.line-height.default | --ds-tooltip-label-line-height-default |
| label font-weight | component.tooltip.label.font-weight.default | --ds-tooltip-label-font-weight-default |
| arrow base | component.tooltip.arrow.base.default | --ds-tooltip-arrow-base-default |
| arrow depth | component.tooltip.arrow.depth.default | --ds-tooltip-arrow-depth-default |
| z-index | semantic.z.tooltip | --ds-z-tooltip |
Usage
When to use
Use tooltips when
Providing supplementary, non-essential info on hover or focus: icon button labels, abbreviation explanations, brief clarifications.
Don't use tooltips when
The information is essential (make it visible by default), the content is interactive — links, buttons, or forms (use Popover), or the content is long (use Modal).
Best practices
Settings
Faça
Use tooltips on icon-only buttons to clarify their purpose. Keep under 80 characters.
Click here to open settings where you can change your theme, language, and notification preferences
Não faça
Put long content, links, buttons, or forms inside tooltips.
Edit document
Faça
Provide supplementary, non-essential information via tooltips.
Critical information only visible on hover
Não faça
Make tooltips the only way to convey critical info. Essential content should be always visible.
Content guidelines
| Rule | Example |
|---|---|
| Under 80 characters | "Edit document" — not a full paragraph |
| Sentence case | "Copy to clipboard" — not "Copy To Clipboard" |
| No period for fragments | "Delete item" — not "Delete item." |
| Text only — no interactive content | No links, buttons, or form elements inside tooltips |
Implementation
- Status
- Stable
- Distribution
- npm package
Installation
npm install ds-tispnpm add ds-tisyarn add ds-tisbun add ds-tisImports
import 'ds-tis/css'
import { initTooltips } from 'ds-tis/tooltip'
initTooltips()Markup
<div class="ds-tooltip ds-tooltip--top">
<button type="button" aria-label="Editar projeto" aria-describedby="edit-tooltip">Editar</button>
<span class="ds-tooltip__content" id="edit-tooltip" role="tooltip">Editar projeto</span>
</div>Web implementation contract
CSS classes
| Class | Description |
|---|---|
ds-tooltip | Wrapper around trigger and tooltip content |
ds-tooltip__content | The tooltip label element (with arrow via ::before) |
ds-tooltip--top | Position tooltip above the trigger |
ds-tooltip--right | Position tooltip to the right |
ds-tooltip--bottom | Position tooltip below the trigger |
ds-tooltip--left | Position tooltip to the left |
Accessibility
Keyboard interaction
| Key | Action |
|---|---|
Tab (to trigger) | Shows tooltip when trigger receives focus |
Escape | Hides tooltip |
Tab (away) | Hides tooltip when focus leaves the trigger |
Accessibility
| WCAG criterion | Requirement | Status |
|---|---|---|
| 1.4.13 Content on Hover/Focus (AA) | Tooltip must be dismissable (Escape), hoverable (mouse can enter tooltip), and persistent (stays while hovered/focused) | ✓ |
| 4.1.2 Name, Role, Value (A) | Tooltip element has role="tooltip", trigger linked via aria-describedby | ✓ |
ARIA attributes summary
role="tooltip" — on the tooltip content element.aria-describedby — on the trigger, pointing to the tooltip's id.Tooltips must appear on both
hover and focus, and be dismissible with Escape.
Output responsibility
Initialize the public runtime after render and destroy it when the owning view unmounts.
Validation evidence
Covered by the stable Storybook, public runtime tests when applicable, keyboard scenarios, responsive checks, and Axe.