Tooltip

A concise tooltip built on the hover-card controller. Custom element

Choosing between components

Tooltip and Hover Card are one custom element with two boxes. variant="tooltip" gives a short non-interactive label that sizes to its content and never scrolls; omit it for a roomier surface holding content worth reading or clicking. Because both are <ui-hover-card>, the host attributes — anchor, placement, open-delay, close-delay — are the same for each and are documented once, on Hover Card.

Tooltip

Copy this markup

<button id="copy-tooltip-anchor" class="ui-button" data-ui-variant="secondary" data-ui-size="sm" type="button" aria-describedby="copy-tooltip" aria-expanded="false">Copy</button>
<ui-hover-card id="copy-tooltip" anchor="copy-tooltip-anchor" variant="tooltip" open-delay="0" close-delay="80" popover="manual" role="tooltip">
  <p>Copy canonical markup</p>
</ui-hover-card>

Install

Styles and registration

import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/core/floating.css'
import '@timelessui/components/css/core/popover.css'
import '@timelessui/components/css/core/button.css'
import '@timelessui/components/css/themes/atmosphere/tokens.css'
import '@timelessui/components/css/themes/atmosphere/button.css'
import '@timelessui/components/css/themes/atmosphere/popover.css'
import '@timelessui/components/register/ui-hover-card'

A register/ import is a side effect: it defines the element as the module evaluates, so it has to run in code the browser loads. To register explicitly instead — to control the timing, or to define into another window — call the function from the matching define/ entry point, which registers nothing on its own:

Explicit registration

import { defineHoverCardElement } from '@timelessui/components/define/ui-hover-card'
defineHoverCardElement()

Anatomy

Parts are authored in your own markup and identified by the selector below, so your CSS can target the same anatomy without loading Timeless styles. Required parts must be present for the component to work. Private data-ui-internal-* hooks are written by the runtime and must never be authored.

Part	Required	Selector	Purpose
trigger	Yes	[data-ui-part~='trigger']	Control the label describes. Point its aria-describedby at the surface.
content	Yes	[popover]	The label. One short, non-interactive line; give it role="tooltip".

Element API

Attributes above are the authoring surface. These are the DOM properties and events the registered element adds once it upgrades.

<ui-hover-card>

Property	Type	Notes
anchor	string	Reflects the anchor attribute.
variant	'tooltip'	Reflects the variant attribute.
placement	'bottom' | 'top' | 'right' | 'left'	Reflects the placement attribute.
openDelayValue	string	Reflects the open-delay attribute.
closeDelayValue	string	Reflects the close-delay attribute.

This element dispatches no component events.

Styling

Root identity: ui-hover-card[variant='tooltip']. Required stylesheets: tokens.css, core/floating.css, core/popover.css, core/button.css, themes/atmosphere/tokens.css, themes/atmosphere/button.css, themes/atmosphere/popover.css.

Set these custom properties to restyle the component:

Custom property	Controls
--ui-tooltip-bg	Surface background. Inverted against the page by default.
--ui-tooltip-fg	Label color, and the border tint is mixed from it.

Design tokens this component reads (30)

These are global Atmosphere tokens. Change them once at the theme level rather than per component.

--ui-accent · --ui-bg-accent · --ui-bg-accent-active · --ui-bg-accent-hover · --ui-bg-control · --ui-bg-control-active · --ui-bg-control-hover · --ui-bg-control-muted · --ui-bg-danger · --ui-bg-danger-active · --ui-bg-danger-hover · --ui-bg-surface · --ui-duration-fast · --ui-ease-standard · --ui-fg · --ui-fg-muted · --ui-focus · --ui-line · --ui-radius-control · --ui-radius-lg · --ui-radius-md · --ui-shadow-control-accent · --ui-shadow-control-active · --ui-shadow-control-danger · --ui-shadow-floating · --ui-shadow-outline-control · --ui-shadow-tooltip · --ui-space-2 · --ui-space-3 · --ui-space-4

Accessibility

Keep the native elements, roles, and relationships shown in the example. Timeless adds only the state and keyboard coordination the platform does not already provide, and it never supplies your accessible names — those depend on your content.

Follows the Tooltip pattern from the ARIA Authoring Practices Guide.

Key	Action
Escape	Close the label while the trigger has focus.

A tooltip names or describes its trigger and nothing else. Point the trigger at it with aria-describedby and give the surface role="tooltip"; Timeless wires relationships, never content. It opens on hover and on keyboard focus, so it is reachable without a mouse, and closes when either leaves. It is deliberately not a disclosure: clicking the trigger does not toggle the label, so a trigger that is also a button keeps its own job on click. The pointer can still be moved onto the label without it disappearing, because WCAG 2.2 SC 1.4.13 requires hover-triggered content to be hoverable — reading a label is not interacting with it. Never put the only copy of anything here — for content the user may want to read at length or click, use Hover Card instead. Both variants share one open-delay / close-delay pair, documented once on Hover Card; a tooltip that should appear faster sets the attribute rather than getting a different default, because one attribute cannot have two.

Verify in context

Automated checks cover axe WCAG 2.2 A and AA rules on every documented route. Keyboard, zoom, forced-colors, and screen-reader review still belong to your application.

Before JavaScript runs

The markup above is complete and usable on its own: native controls submit, labels associate, and authored ARIA is already correct. Registration adds state synchronisation, focus management, and keyboard coordination on top of it.

More examples

Open Tooltip in StoryLite for variants, controls, and manual testing.