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>
);
});.hover-card-default {
margin: 0;
font-family: inherit;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
}
.hover-card-default-trigger,
.hover-card-default-link {
border-radius: 4px;
color: light-dark(#006ce9, #4cb8ff);
font-weight: 500;
text-decoration: none;
}
.hover-card-default-trigger:hover,
.hover-card-default-link:hover {
text-decoration: underline;
}
.hover-card-default-trigger:focus-visible,
.hover-card-default-link:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The Content is a popover in the top layer; the library sets its position */
.hover-card-default-content {
gap: 12px;
box-sizing: border-box;
width: 280px;
padding: 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
overflow: visible;
}
/* Set display only while open: it would override the hidden state of the popover */
.hover-card-default-content:popover-open {
display: flex;
}
/* Fade in when it opens */
.hover-card-default-content:popover-open {
transition: opacity 150ms ease;
@starting-style {
opacity: 0;
}
}
.hover-card-default-avatar {
display: grid;
flex-shrink: 0;
place-items: center;
width: 40px;
height: 40px;
border-radius: 9999px;
background: #009dfd;
color: #ffffff;
font-size: 14px;
font-weight: 600;
}
.hover-card-default-body {
display: flex;
flex-direction: column;
align-items: flex-start;
}
.hover-card-default-name {
margin: 0;
font-size: 14px;
font-weight: 600;
}
.hover-card-default-bio {
margin: 2px 0 8px;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.hover-card-default-link {
font-size: 13px;
}
/* A rotated square on the edge facing the Trigger */
.hover-card-default-arrow {
width: 10px;
height: 10px;
background: inherit;
border: inherit;
rotate: 45deg;
}
.hover-card-default-arrow[data-side="bottom"] {
margin-top: -6px;
border-right: none;
border-bottom: none;
}
.hover-card-default-arrow[data-side="top"] {
margin-bottom: -6px;
border-left: none;
border-top: none;
}Installation#
Install the individual package, or use @leve-ui/core to get every component at once:
pnpm add @leve-ui/hover-cardnpm install @leve-ui/hover-cardyarn add @leve-ui/hover-cardbun add @leve-ui/hover-cardpnpm add @leve-ui/corenpm install @leve-ui/coreyarn add @leve-ui/corebun add @leve-ui/coreAnatomy#
import { HoverCard } from '@leve-ui/hover-card'; // or '@leve-ui/core'
<HoverCard.Root>
<HoverCard.Trigger />
<HoverCard.Content>
<HoverCard.Arrow />
</HoverCard.Content>
</HoverCard.Root>
| Part | Element | Description |
|---|---|---|
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.
| Use | When |
|---|---|
| Tooltip | A short text that describes a button. |
| Hover Card | A rich preview of a link, which may contain links. |
| Popover | A 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.
import {
$,
component$,
type PropsOf,
type QRL,
Slot,
sync$,
useSignal,
useStyles$,
} from '@builder.io/qwik';
import { HoverCard } from '@leve-ui/hover-card';
import styles from './custom-trigger.css?inline';
type ClientLinkProps = PropsOf<'a'> & {
onNavigate$?: QRL<(href: string) => void>;
};
// Example of a router link component (such as Qwik City's <Link>) that spreads received props onto <a>
const ClientLink = component$<ClientLinkProps>(({ onNavigate$, onClick$, ...props }) => {
const preventDefault$ = sync$((event: MouseEvent) => {
event.preventDefault();
});
const handleClick$ = $(() => {
if (props.href) {
onNavigate$?.(props.href);
}
});
return (
<a {...props} onClick$={[preventDefault$, handleClick$, onClick$]}>
<Slot />
</a>
);
});
export default component$(() => {
useStyles$(styles);
const visited = useSignal<string | null>(null);
return (
<p class="hover-card-custom-trigger">
Reviewed by{' '}
<HoverCard.Root>
<HoverCard.Trigger
as={ClientLink}
href="/users/ada"
onNavigate$={$((href: string) => {
visited.value = href;
})}
class="hover-card-custom-trigger-trigger"
>
@ada
</HoverCard.Trigger>
{/* A preview only: the profile page has the same information */}
<HoverCard.Content sideOffset={8} class="hover-card-custom-trigger-content">
{/* Only inline elements (span) inside: the card is in a <p> */}
<span class="hover-card-custom-trigger-avatar" aria-hidden="true">
AL
</span>
<span class="hover-card-custom-trigger-body">
<span class="hover-card-custom-trigger-name">Ada Lovelace</span>
<span class="hover-card-custom-trigger-bio">
Writes the first programs. Joined in 1843.
</span>
<a href="#ada" class="hover-card-custom-trigger-link">
View profile
</a>
</span>
<HoverCard.Arrow class="hover-card-custom-trigger-arrow" />
</HoverCard.Content>
</HoverCard.Root>{' '}
yesterday.
{visited.value && (
<span class="hover-card-custom-trigger-status"> Navigated to {visited.value}</span>
)}
</p>
);
});.hover-card-custom-trigger {
margin: 0;
font-family: inherit;
font-size: 14px;
color: light-dark(#0f172a, #ffffff);
}
.hover-card-custom-trigger-trigger,
.hover-card-custom-trigger-link {
border-radius: 4px;
color: light-dark(#006ce9, #4cb8ff);
font-weight: 500;
text-decoration: none;
}
.hover-card-custom-trigger-trigger:hover,
.hover-card-custom-trigger-link:hover {
text-decoration: underline;
}
.hover-card-custom-trigger-trigger:focus-visible,
.hover-card-custom-trigger-link:focus-visible {
outline: 2px solid #009dfd;
outline-offset: 2px;
}
/* The Content is a popover in the top layer; the library sets its position */
.hover-card-custom-trigger-content {
gap: 12px;
box-sizing: border-box;
width: 280px;
padding: 14px;
border: 1px solid light-dark(#cbd5e1, #ffffff3d);
border-radius: 6px;
background: light-dark(#ffffff, #1b2045);
color: light-dark(#0f172a, #ffffff);
font-family: inherit;
box-shadow: 0 8px 24px rgb(15 23 42 / 0.18);
overflow: visible;
}
/* Set display only while open: it would override the hidden state of the popover */
.hover-card-custom-trigger-content:popover-open {
display: flex;
}
/* Fade in when it opens */
.hover-card-custom-trigger-content:popover-open {
transition: opacity 150ms ease;
@starting-style {
opacity: 0;
}
}
.hover-card-custom-trigger-avatar {
display: grid;
flex-shrink: 0;
place-items: center;
width: 40px;
height: 40px;
border-radius: 9999px;
background: #009dfd;
color: #ffffff;
font-size: 14px;
font-weight: 600;
}
.hover-card-custom-trigger-body {
display: flex;
flex-direction: column;
align-items: flex-start;
}
.hover-card-custom-trigger-name {
margin: 0;
font-size: 14px;
font-weight: 600;
}
.hover-card-custom-trigger-bio {
margin: 2px 0 8px;
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}
.hover-card-custom-trigger-link {
font-size: 13px;
}
/* A rotated square on the edge facing the Trigger */
.hover-card-custom-trigger-arrow {
width: 10px;
height: 10px;
background: inherit;
border: inherit;
rotate: 45deg;
}
.hover-card-custom-trigger-arrow[data-side="bottom"] {
margin-top: -6px;
border-right: none;
border-bottom: none;
}
.hover-card-custom-trigger-arrow[data-side="top"] {
margin-bottom: -6px;
border-left: none;
border-top: none;
}
.hover-card-custom-trigger-status {
font-size: 13px;
color: light-dark(#475569, #c9ddf0);
}API Reference#
Root#
| Prop | Default | Type |
|---|---|---|
| ids | – | { trigger?: string; content?: string } Overrides the element IDs of the parts. |
| defaultOpen | false | boolean 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. |
| openDelay | 700 | number The delay in ms before the card opens when the pointer rests on the Trigger or the Trigger is focused. |
| closeDelay | 300 | number 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 attribute | Value |
|---|---|
data-leve-hover-card | Always present |
data-state | "open" | "closed" |
Trigger#
| Prop | Default | Type |
|---|---|---|
| as | 'a' | keyof HTMLElementTagNameMap | Component<any> The element or component to render instead of |
Also accepts all <a> attributes.
| Data attribute | Value |
|---|---|
data-leve-hover-card-trigger | Always present |
data-state | "open" | "closed" |
Content#
| Prop | Default | Type |
|---|---|---|
| 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. |
| sideOffset | 0 | number The distance from the Trigger in px. |
| alignOffset | 0 | number The offset along the side in px. |
| avoidCollisions | true | boolean Whether to flip and shift the card to keep it in the viewport. |
| collisionPadding | 0 | number The padding from the viewport edges when avoiding collisions, in px. |
| arrowPadding | 0 | number The padding between the arrow and the corners of the card, in px. |
Also accepts all <span> attributes.
| Data attribute | Value |
|---|---|
data-leve-hover-card-content | Always present |
data-state | "open" | "closed" |
data-side | The final side after flipping: "top" | "right" | "bottom" | "left" |
data-align | "start" | "center" | "end" |
| CSS variable | Value |
|---|---|
--leve-hover-card-anchor-width | The width of the Trigger |
--leve-hover-card-anchor-height | The height of the Trigger |
--leve-hover-card-available-width | The width available in the viewport |
--leve-hover-card-available-height | The 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 attribute | Value |
|---|---|
data-leve-hover-card-arrow | Always present |
data-side | The 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 aftercloseDelay(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.Arrowis hidden from assistive technologies witharia-hidden="true".
Keyboard Interactions#
| Key | Description |
|---|---|
Tab | Focusing the link shows the card after the delay; leaving it hides the card. |
Escape | Hides the card. Focus stays on the link. |