# Hover Card

Open supporting content from pointer or keyboard intent. (Custom element.)

Reference: https://timeless.build/docs/components/hover-card/

> **Choosing between components.** Use Hover Card for a surface holding content worth reading or clicking. For a single short label on hover or focus, [Tooltip](/docs/components/tooltip/) is the same element with `variant="tooltip"` and a box sized for one line.

## Markup

```html
<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

```js
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:

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

## Anatomy

Parts are authored in your own markup and identified by the selector below. 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 |
| `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`.
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), global and set at the theme level: `--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 markup. 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](https://www.w3.org/WAI/ARIA/apg/patterns/tooltip/) 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.