Hover Card

Open supporting content from pointer or keyboard intent. Custom element

<ui-hover-card>
  <button class="ui-button" data-ui-variant="secondary" data-ui-part="trigger" type="button" aria-controls="hover-reference" aria-expanded="false">Component contract</button>
  <div id="hover-reference" popover="manual" role="group" aria-labelledby="hover-reference-title" aria-describedby="hover-reference-description">
    <h2 id="hover-reference-title">Public contract</h2>
    <p id="hover-reference-description">Stable anatomy, attributes, and events.</p>
  </div>
</ui-hover-card>

Install

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:

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']`	Element that receives hover and focus intent.
`content`	Yes	`[popover]`	The surface.

Attributes

Every value below is implemented by the stylesheets this component ships. Boolean attributes are presence-based: author the attribute with no value, or omit it.

Attribute	Values	Default	Description
`anchor`	any `string`	—	Id of an element to anchor against instead of the trigger. Use it when the visual anchor differs from the control that opens the card.
`variant`	`tooltip`	—	Set `tooltip` for the compact tooltip treatment. Omit for the roomier hover-card surface.
`placement`	`bottom` · `top` · `right` · `left`	`bottom`	Preferred side of the anchor.
`open-delay`	any `number`	`180`	Milliseconds of hover or focus intent before opening. The resolved number is available on the read-only `openDelay` property.
`close-delay`	any `number`	`100`	Milliseconds after the pointer leaves before closing, so the user can cross the gap into the surface. The resolved number is available on the read-only `closeDelay` property.

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, documented above.
`variant`	`'tooltip'`	Reflects the `variant` attribute, documented above.
`placement`	`'bottom' \| 'top' \| 'right' \| 'left'`	Reflects the `placement` attribute, documented above.
`openDelayValue`	`string`	Reflects the `open-delay` attribute, documented above.
`closeDelayValue`	`string`	Reflects the `close-delay` attribute, documented above.

This element dispatches no component events.

Styling

Root identity: ui-hover-card. 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-floating-offset`	Gap between the anchor and the surface.

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 surface while the trigger has focus.

The card opens on both pointer hover and keyboard focus, so it is reachable without a mouse, and clicking the trigger toggles it. close-delay keeps it open while the pointer crosses the gap into the surface, and focus moving into the surface cancels the close outright — so a link or a button inside it is reachable with Tab, not only with a pointer. Under variant="tooltip" the click toggle is dropped — a tooltip describes its trigger rather than disclosing a surface — while the gap-crossing behavior stays, because WCAG 2.2 SC 1.4.13 requires it. See [Tooltip](/docs/components/tooltip/). Never put the only copy of important content here.

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 Hover Card in StoryLite for variants, controls, and manual testing.