Skip to main content

Starwind UI v3.0 is now available! Migration guide

Hover Card

Installation

Usage

---
import { Avatar, AvatarFallback, AvatarImage } from "@/components/starwind/avatar";
import { Button } from "@/components/starwind/button";
import { HoverCard, HoverCardContent, HoverCardTrigger } from "@/components/starwind/hover-card";
---
<HoverCard>
<HoverCardTrigger asChild>
<Button variant="outline">@starwind</Button>
</HoverCardTrigger>
<HoverCardContent class="w-80" align="start">
<div class="flex justify-between gap-4">
<Avatar class="shrink-0">
<AvatarImage src="https://i.pravatar.cc/150?u=starwind" alt="Starwind UI" />
<AvatarFallback>SW</AvatarFallback>
</Avatar>
<div class="space-y-1">
<h4 class="text-sm font-semibold">Starwind UI</h4>
<p class="text-muted-foreground text-sm">
Accessible Astro components styled with Tailwind CSS.
</p>
<span class="text-muted-foreground block pt-2 text-xs">Built for Astro developers</span>
</div>
</div>
</HoverCardContent>
</HoverCard>

Composition

Use a trigger and content inside the root:

HoverCard
├── HoverCardTrigger
└── HoverCardContent

When to Use

Use Hover Card for optional context that appears when a trigger receives hover or keyboard focus.

Profile Preview

Use asChild on the trigger when you want to reuse an existing interactive component like Button.

Side and Alignment

Use side, align, and sideOffset on HoverCardContent to control placement.

Non-hoverable Content

By default, moving the pointer from trigger to content keeps the card open. Set disableHoverableContent to close immediately when leaving the trigger.

API Reference

Styled Component API

These props are added or materially changed by the installed styled component. Standard HTML attributes remain available through the inherited interfaces noted below. Expand a prop to see named type definitions and framework-specific imports. Follow the Primitive and Runtime links for lower-level behavior props.

Hover Card Trigger

Inherits a attributes.

Contains the following additional props:

Prop Type Default Toggle details
asChild boolean false
Description
Merges the component behavior and props into its child element.
Classification
Primitive override
Primitive prop
preview-card.Trigger.asChild
closeDelay number —
Description
Sets the delay in milliseconds before closing.
Classification
Primitive override
Primitive prop
preview-card.Trigger.closeDelay
openDelay number —
Description
Sets the delay in milliseconds before opening.
Classification
Primitive override
Primitive prop
preview-card.Trigger.openDelay

Hover Card Content

Inherits div attributes.

Contains the following additional props:

Prop Type Default Toggle details
disablePortal boolean false
Description
Keeps the public Portal wrapper inline instead of moving it to a target.
Classification
Wrapper prop
portalContainer string —
Description
Sets the CSS selector for the public Portal wrapper target.
Classification
Wrapper prop
positionerClass string —
Description
Adds classes to the generated floating positioner element.
Classification
Wrapper prop
sideOffset number 4
Description
Sets the distance in pixels between floating content and its anchor.
Classification
Primitive override
Primitive prop
preview-card.Popup.sideOffset

Primitive And Runtime API

Use these references when you need the lower-level behavior APIs behind Hover Card.

Runtime API

Preview Card primitive
createPreviewCard from @starwind-ui/runtime/preview-card

Changelog

View version history v2.3.0 6 releases

v2.3.0

  • In Svelte, a defined open that you pass when HoverCard mounts now stays under your control, as in React and Vue. To change it, use bind: or update your state in the change callback. A form reset keeps it. If you pass undefined at mount, HoverCard keeps its own state.
  • Fixed Hover Card in Vue and Svelte staying hidden when its popup is replaced while open, for example when the key on the content changes.
  • Fixed a HoverCard trigger on a link or span that stayed disabled when a framework wrote disabled="false". On a native form control, any disabled attribute still disables it.

v2.2.1

  • Vue Preview Card keeps its previous open state when an open or close action is canceled.
  • Reduced background work when a React page uses multiple menus, tooltips, or other portals.
  • Fixed nested Svelte overlays inside a dialog appearing behind their parent or failing to receive clicks.
  • Fixed open content losing its position at the trigger when the React or Vue component updates.
  • Fixed nested overlays appearing behind their parent in Vue and Svelte. Overlays can now render under the document body; if custom CSS or DOM queries require them to stay inside a parent, set a portal container or add data-floating-root to that parent.
  • Fixed React 18 retaining removed popup elements when the parent component stays mounted.

v2.2.0

  • Added portalContainer and disablePortal to HoverCardContent for custom portal targets and inline rendering.

v2.1.0

  • Added positionerClass to HoverCardContent so the floating positioner can be styled directly.
  • The default z-index is now on the positioner. Before, it was on the content.

v2.0.2

  • The default export in index.ts now has a name, HoverCardParts, so framework tools show a clear name.

v2.0.0

  • Hover Card now gets its behavior from Starwind Runtime. Runtime handles opening on hover and focus, placement next to the trigger, and closing.
  • See the Preview Card Primitive for the unstyled parts and the behavior API.