Tooltip
Tooltips reveal a short hint about an element on hover or focus, anchored with a directional pointer.
Components · Messaging
A tooltip is a small, transient label anchored to a trigger element with a directional pointer. Namirial tooltips are built from --nm-tooltip-* tokens defined in namirial-theme.css, position in four sides × three alignments, and default to the primary intent.
Overview
A tooltip supplements a control that's already understandable on its own — it clarifies an icon-only button, spells out an abbreviation, or adds a hint. It appears on hover/focus of its trigger and disappears the moment that trigger loses hover/focus.
When to use
Use a tooltip when:
- The trigger is already usable without it (an icon button, a truncated label) and the tooltip only adds a supplementary hint.
- The content is a short, single idea — a label, a shortcut, a brief clarification.
Consider another component when:
- The content needs to stay open while the user reads or interacts with it, or contains its own actions — use Popover.
- The information is essential to complete the task, not supplementary — put it inline instead of hiding it behind hover.
- The trigger is touch-only — hover-based tooltips are unreliable on touch devices; pair with a tap-to-toggle popover instead.
Anatomy
A tooltip is an icon, a text run, and a triangular pointer positioned by a ::before pseudo-element that points back at the trigger.
Tokens and values that drive each part
| Part | Role | Source |
|---|---|---|
| Container | Fill | --nm-tooltip-bg |
| Container | Border | --nm-tooltip-border |
| Container | Radius / padding / gap | border-radius: 8px · padding: 8px · gap: 8px |
| Container | Size bounds | min-width: 56px · max-width: 320px |
| Icon / text | Color | --nm-tooltip-fg |
| Pointer | Fill | --nm-tooltip-border (8px triangle, via ::before) |
| Shadow | Fixed | 2px 2px 4px rgba(0,0,0,0.25) |
Positions
Tooltip supports four sides (top, bottom, left, right), each with a centered default plus -start/-end alignment — 12 positions in total, each carrying its own pointer placement.
Pick the side with the most free space around the trigger; fall back to the opposite side if the tooltip would clip the viewport.
Intent variants
Tooltip ships seven intents, defaulting to primary.
Reach for a non-default intent only when the hint itself carries that meaning (e.g. warning on a control that has a caveat) — most tooltips should stay primary.
Content types
Text only
Icon + text
Light & dark theme
Tooltip tokens read from the shared --palette-callout-* scale, so no per-component dark override is needed.
Both previews are locked — they don't follow the page theme switcher.
Do & don't
aria-label.Accessibility
Semantics
- Connect the tooltip to its trigger with
aria-describedby, pointing at the tooltip'sid. - Use
role="tooltip"on the container.
Keyboard
- A tooltip must appear on keyboard focus of its trigger, not only on mouse hover — otherwise keyboard users never see it.
- Dismiss on
Escapeand on blur; never require a click to close it.
Timing
- Don't rely on a tooltip alone to convey information required to complete a task — mouse-only hover and short auto-dismiss timers make it an unreliable single source of truth.
Token reference
| Token | Role |
|---|---|
| --nm-tooltip-bg | Container fill — recolored per intent |
| --nm-tooltip-border | Container border and pointer fill — recolored per intent |
| --nm-tooltip-fg | Icon and text color — recolored per intent |
Implementation
Positioning and show/hide timing need a small amount of JavaScript (or a floating-UI library); the markup and visuals are pure CSS.
<link rel="stylesheet" href="namirial-theme.css">
<div class="nm-tooltip nm-tooltip--top" role="tooltip" id="tip-1">
<span class="nm-tooltip__icon" aria-hidden="true"><!-- icon --></span>
<span class="nm-tooltip__text">Autosaves every 30 seconds</span>
</div>CSS classes
| Class | Values | Default |
|---|---|---|
nm-tooltip--{position} | top · top-start · top-end · bottom · bottom-start · bottom-end · left · left-start · left-end · right · right-start · right-end | — |
nm-tooltip--{intent} | primary · secondary · accent · info · positive · negative · warning — omit for primary | — (primary) |
nm-tooltip__icon | Leading icon slot, 24×24px | — |
nm-tooltip__text | Text content | — |