Search docs

Hover Card

A preview of a link's content, shown when the link is hovered or focused.

There is no WAI-ARIA APG pattern for hover cards. A hover card is a visual preview for pointer users: the page behind the link must have the same information, since the card is not connected to the link for assistive technologies.

Reviewed by @adaAda LovelaceWrites the first programs. Joined in 1843.View profile yesterday.

import { component$, useStyles$ } from '@builder.io/qwik';
import { HoverCard } from '@leve-ui/hover-card';
import styles from './default.css?inline';

export default component$(() => {
  useStyles$(styles);

  return (
    <p class="hover-card-default">
      Reviewed by{' '}
      <HoverCard.Root>
        <HoverCard.Trigger href="#ada" class="hover-card-default-trigger">
          @ada
        </HoverCard.Trigger>
        {/* A preview only: the profile page has the same information */}
        <HoverCard.Content sideOffset={8} class="hover-card-default-content">
          {/* Only inline elements (span) inside: the card is in a <p> */}
          <span class="hover-card-default-avatar" aria-hidden="true">
            AL
          </span>
          <span class="hover-card-default-body">
            <span class="hover-card-default-name">Ada Lovelace</span>
            <span class="hover-card-default-bio">Writes the first programs. Joined in 1843.</span>
            <a href="#ada" class="hover-card-default-link">
              View profile
            </a>
          </span>
          <HoverCard.Arrow class="hover-card-default-arrow" />
        </HoverCard.Content>
      </HoverCard.Root>{' '}
      yesterday.
    </p>
  );
});

Installation#

Install the individual package, or use @leve-ui/core to get every component at once:

pnpm add @leve-ui/hover-card

Anatomy#

import { HoverCard } from '@leve-ui/hover-card'; // or '@leve-ui/core'

<HoverCard.Root>
  <HoverCard.Trigger />
  <HoverCard.Content>
    <HoverCard.Arrow />
  </HoverCard.Content>
</HoverCard.Root>
PartElementDescription
HoverCard.Root<span>Wraps the parts and holds the open state. An inline element, so it fits in text.
HoverCard.Trigger<a>The link that shows the card. Use as to render another element or a router link component.
HoverCard.Content<span>The card, a popover="manual" element in the top layer. A <span> so that it can be placed in a paragraph: use only inline elements inside it.
HoverCard.Arrow<span>Optional. An arrow pointing at the Trigger, drawn with CSS.

Use as to render HoverCard.Trigger as a router link component such as Qwik City's <Link> or another element. A component passed to as must spread the props it receives onto a single element, including id, aria-*, data-*, and on*$ event handlers.

UseWhen
TooltipA short text that describes a button.
Hover CardA rich preview of a link, which may contain links.
PopoverA panel that the user opens on purpose and works in, with the keyboard too.

Examples#

Custom Trigger#

Pass a router link component such as Qwik City's <Link> to as on HoverCard.Trigger for client-side navigation while keeping the hover card behavior.

Reviewed by @adaAda LovelaceWrites the first programs. Joined in 1843.View profile yesterday.

API Reference#

Root#

PropDefaultType
ids–{ trigger?: string; content?: string }

Overrides the element IDs of the parts.

defaultOpenfalseboolean

Whether the card is shown initially (uncontrolled).

bind:open–Signal<boolean>

A signal with the open state (controlled).

onOpenChange$–QRL<(open: boolean) => void>

Called when the card is shown or hidden by a user interaction.

openDelay700number

The delay in ms before the card opens when the pointer rests on the Trigger or the Trigger is focused.

closeDelay300number

The delay in ms before the card closes when the pointer leaves, so that the pointer can move onto it.

Also accepts all <span> attributes.

Data attributeValue
data-leve-hover-cardAlways present
data-state"open" | "closed"

Trigger#

PropDefaultType
as'a'keyof HTMLElementTagNameMap | Component<any>

The element or component to render instead of <a>. A component must spread the props it receives onto one element.

Also accepts all <a> attributes.

Data attributeValue
data-leve-hover-card-triggerAlways present
data-state"open" | "closed"

Content#

PropDefaultType
side'bottom''top' | 'right' | 'bottom' | 'left'

The side of the Trigger to place the card on. It flips when there is no room.

align'center''start' | 'center' | 'end'

The alignment along that side.

sideOffset0number

The distance from the Trigger in px.

alignOffset0number

The offset along the side in px.

avoidCollisionstrueboolean

Whether to flip and shift the card to keep it in the viewport.

collisionPadding0number

The padding from the viewport edges when avoiding collisions, in px.

arrowPadding0number

The padding between the arrow and the corners of the card, in px.

Also accepts all <span> attributes.

Data attributeValue
data-leve-hover-card-contentAlways present
data-state"open" | "closed"
data-sideThe final side after flipping: "top" | "right" | "bottom" | "left"
data-align"start" | "center" | "end"
CSS variableValue
--leve-hover-card-anchor-widthThe width of the Trigger
--leve-hover-card-anchor-heightThe height of the Trigger
--leve-hover-card-available-widthThe width available in the viewport
--leve-hover-card-available-heightThe height available in the viewport

The Content gets inline position, top and left while it is open. Set display (for example flex) only on :popover-open: on the Content itself, it would override the browser's display: none of the closed popover.

Arrow#

No props of its own. Accepts all <span> attributes.

Data attributeValue
data-leve-hover-card-arrowAlways present
data-sideThe final side of the Content

Accessibility#

  • The card opens after openDelay (700 ms) when the pointer rests on the link or the link is focused, and closes after closeDelay (300 ms) when the pointer leaves, when focus leaves, or on Escape.
  • Moving the pointer onto the card keeps it open, so its links can be clicked (WCAG 1.4.13 Content on Hover or Focus).
  • The card has no role and is not referenced from the link, and focus never moves into it. Do not put information or actions only in the card: keyboard and screen reader users reach them on the linked page.
  • HoverCard.Arrow is hidden from assistive technologies with aria-hidden="true".

Keyboard Interactions#

KeyDescription
TabFocusing the link shows the card after the delay; leaving it hides the card.
EscapeHides the card. Focus stays on the link.