Kobalte.v0.12.1

Hover Card

Allows sighted users to preview content available behind a link.

Import

ts
import { HoverCard } from "@kobalte/core";
ts
import { HoverCard } from "@kobalte/core";

Features

  • Opens on hover only.
  • Supports custom open and close delays.
  • Optionally render a pointing arrow.
  • Ignored by screen readers.
  • Can be controlled or uncontrolled.

Anatomy

The hovercard consists of:

  • HoverCard.Root: The root container for a hovercard.
  • HoverCard.Trigger: The link that opens the hovercard.
  • HoverCard.Portal: Portals its children into the body when the hovercard is open.
  • HoverCard.Content: Contains the content to be rendered when the hovercard is open.
  • HoverCard.Arrow: An optional arrow element to render alongside the hovercard.
tsx
<HoverCard.Root>
<HoverCard.Trigger />
<HoverCard.Portal>
<HoverCard.Content>
<HoverCard.Arrow />
</HoverCard.Content>
</HoverCard.Portal>
</HoverCard.Root>
tsx
<HoverCard.Root>
<HoverCard.Trigger />
<HoverCard.Portal>
<HoverCard.Content>
<HoverCard.Arrow />
</HoverCard.Content>
</HoverCard.Portal>
</HoverCard.Root>

Example

Usage

Default open

An initial, uncontrolled open value can be provided using the defaultOpen prop.

tsx
<HoverCard.Root defaultOpen>...</HoverCard.Root>
tsx
<HoverCard.Root defaultOpen>...</HoverCard.Root>

Controlled open

The open prop can be used to make the open state controlled. The onOpenChange event is fired when the user pointer enter or leave the trigger, and receives the new value.

tsx
import { createSignal } from "solid-js";
function ControlledExample() {
const [open, setOpen] = createSignal(false);
return (
<HoverCard.Root open={open()} onOpenChange={setOpen}>
...
</HoverCard.Root>
);
}
tsx
import { createSignal } from "solid-js";
function ControlledExample() {
const [open, setOpen] = createSignal(false);
return (
<HoverCard.Root open={open()} onOpenChange={setOpen}>
...
</HoverCard.Root>
);
}

Origin-aware animations

We expose a CSS custom property --kb-hovercard-content-transform-origin which can be used to animate the content from its computed origin.

css
/* style.css */
.hovercard__content {
transform-origin: var(--kb-hovercard-content-transform-origin);
animation: contentHide 250ms ease-in forwards;
}
.hovercard__content[data-expanded] {
animation: contentShow 250ms ease-out;
}
@keyframes contentShow {
from {
opacity: 0;
transform: scale(0.96);
}
to {
opacity: 1;
transform: scale(1);
}
}
@keyframes contentHide {
from {
opacity: 1;
transform: scale(1);
}
to {
opacity: 0;
transform: scale(0.96);
}
}
css
/* style.css */
.hovercard__content {
transform-origin: var(--kb-hovercard-content-transform-origin);
animation: contentHide 250ms ease-in forwards;
}
.hovercard__content[data-expanded] {
animation: contentShow 250ms ease-out;
}
@keyframes contentShow {
from {
opacity: 0;
transform: scale(0.96);
}
to {
opacity: 1;
transform: scale(1);
}
}
@keyframes contentHide {
from {
opacity: 1;
transform: scale(1);
}
to {
opacity: 0;
transform: scale(0.96);
}
}

API Reference

HoverCard.Root

PropDescription
openboolean
The controlled open state of the hovercard.
defaultOpenboolean
The default open state when initially rendered. Useful when you do not need to control the open state.
onOpenChange(open: boolean) => void
Event handler called when the open state of the hovercard changes.
openDelaynumber
The duration from when the mouse enters the trigger until the hovercard opens.
closeDelaynumber
The duration from when the mouse leaves the trigger or content until the hovercard closes.
ignoreSafeAreaboolean
Whether to close the hovercard even if the user cursor is inside the safe area between the trigger and hovercard.
idstring
A unique identifier for the component. The id is used to generate id attributes for nested components. If no id prop is provided, a generated id will be used.
forceMountboolean
Used to force mounting the hovercard (portal and content) when more control is needed. Useful when controlling animation with SolidJS animation libraries.

HoverCard.Root also accepts the following props to customize the placement of the HoverCard.Content.

PropDescription
getAnchorRect(anchor?: HTMLElement) => AnchorRect | undefined
Function that returns the anchor element's DOMRect.
placementPlacement
The placement of the hovercard.
gutternumber
The distance between the hovercard and the trigger element. By default, it's 0 plus half of the arrow offset, if it exists.
shiftnumber
The skidding of the hovercard along the trigger element.
flipboolean | string
Controls the behavior of the hovercard when it overflows the viewport:
- If a boolean, specifies whether the hovercard should flip to the opposite side when it overflows.
- If a string, indicates the preferred fallback placements when it overflows.
The placements must be spaced-delimited, e.g. "top left".
slideboolean
Whether the hovercard should slide when it overflows.
overlapboolean
Whether the hovercard can overlap the trigger element when it overflows.
sameWidthboolean
Whether the hovercard should have the same width as the trigger element. This will be exposed to CSS as --kb-popper-anchor-width.
fitViewportboolean
Whether the hovercard should fit the viewport. If this is set to true, the hovercard content will have maxWidth and maxHeight set to the viewport size. This will be exposed to CSS as --kb-popper-available-width and --kb-popper-available-height.
hideWhenDetachedboolean
Whether to hide the hovercard when the trigger element becomes occluded.
detachedPaddingnumber
The minimum padding in order to consider the trigger element occluded.
arrowPaddingnumber
The minimum padding between the arrow and the hovercard corner.
overflowPaddingnumber
The minimum padding between the hovercard and the viewport edge. This will be exposed to CSS as --kb-popper-overflow-padding.

HoverCard.Trigger

HoverCard.Trigger consists of Link.

Data attributeDescription
data-expandedPresent when the hovercard is open.
data-closedPresent when the hovercard is close.

HoverCard.Content share the same data-attributes.

Rendered elements

ComponentDefault rendered element
HoverCard.Rootnone
HoverCard.Triggera
HoverCard.PortalPortal
HoverCard.Contentdiv
HoverCard.Arrowdiv

Accessibility

Keyboard Interactions

The hover card is intended for mouse users only so will not respond to keyboard navigation.