Hover Card

Open supporting content from pointer or keyboard intent. Custom element

Choosing between components

Use Hover Card for a richer preview surface. For a single short label on hover or focus, Tooltip is the same element with tighter styling.

Hover Card

Copy this markup

<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

Styles and registration

import '@timelessui/components/css/tokens.css'
import '@timelessui/components/css/button.css'
import '@timelessui/components/css/popover.css'
import '@timelessui/components/define/ui-hover-card'

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, button.css, popover.css.

This component adds no custom properties of its own. Restyle it through the design tokens or your own CSS.

Design tokens this component reads (29)

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-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. close-delay keeps it open while the pointer crosses the gap into the surface. Never put the only copy of important content here.

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