HoverCard component — a rich floating panel revealed on hover with configurable delays.

A HoverCard is used to show a preview or supplementary information about a linked element when the user hovers over it. It is more powerful than a Tooltip because it can contain structured content — avatars, dates, descriptions, action links — and it has independent open and close delays so users can move into the panel without it disappearing.

Unlike a Popover, a HoverCard is triggered by hover (not click) and carries role="tooltip" semantics — it is supplementary information, not a required step in a workflow.

Typical Use Cases

• User profile previews on @mention links in chat or comments
• Repository/project summaries on hover in a dashboard list
• Link preview cards (URL, title, description) in rich text
• Product card previews in an e-commerce catalogue

The PhiaHoverCard hook manages:

• Configurable open delay (prevents flash on quick cursor movement)
• Configurable close delay (allows the user to move cursor into the card)
• Smart viewport positioning and edge flipping
• Mouse and focus event handling

Sub-components

Hook Setup

Copy the hook via mix phia.add hover_card, then register it in app.js:

# assets/js/app.js
import PhiaHoverCard from "./hooks/hover_card"

let liveSocket = new LiveSocket("/live", Socket, {
  hooks: { PhiaHoverCard }
})

Basic Example — User Profile Preview

The canonical use case: hovering a username shows a brief profile card.

<.hover_card id="user-card-42">
  <.hover_card_trigger hover_card_id="user-card-42">
    <.link href="/users/janedoe" class="font-medium hover:underline">
      @janedoe
    </.link>
  </.hover_card_trigger>
  <.hover_card_content hover_card_id="user-card-42">
    <div class="flex gap-3">
      <.avatar src={@user.avatar_url} alt={@user.name} />
      <div>
        <p class="font-semibold">{@user.name}</p>
        <p class="text-sm text-muted-foreground">@{@user.handle}</p>
        <p class="text-sm text-muted-foreground mt-1">
          Joined {Calendar.strftime(@user.joined_at, "%B %Y")}
        </p>
      </div>
    </div>
    <p class="mt-3 text-sm">{@user.bio}</p>
  </.hover_card_content>
</.hover_card>

Example — Repository Preview

Show project metadata on hover in a list view:

<.hover_card id="repo-card-phiaui" open_delay={400} close_delay={150}>
  <.hover_card_trigger hover_card_id="repo-card-phiaui">
    <.link href="/repos/phiaui">{@repo.name}</.link>
  </.hover_card_trigger>
  <.hover_card_content hover_card_id="repo-card-phiaui" side="right">
    <p class="font-semibold">{@repo.name}</p>
    <p class="text-sm text-muted-foreground">{@repo.description}</p>
    <div class="flex gap-4 mt-2 text-xs text-muted-foreground">
      <span>⭐ {@repo.stars}</span>
      <span>🍴 {@repo.forks}</span>
      <span>{@repo.language}</span>
    </div>
  </.hover_card_content>
</.hover_card>

Example — Custom Positioning

Use side="top" when the trigger is near the bottom of the viewport:

<.hover_card id="bottom-card" side="top" open_delay={200} close_delay={100}>
  <.hover_card_trigger hover_card_id="bottom-card">
    <span class="cursor-help underline decoration-dotted">Learn more</span>
  </.hover_card_trigger>
  <.hover_card_content hover_card_id="bottom-card" side="top">
    <p class="text-sm">Detailed explanation of this feature.</p>
  </.hover_card_content>
</.hover_card>

Side Values

The hook may flip to the opposite side if the preferred side would overflow the viewport.

Delay Tuning

Accessibility

• hover_card_trigger/1 sets aria-describedby pointing at the content panel, so screen readers announce the card content when focus lands on the trigger (keyboard users receive the same information as mouse users)
• hover_card_content/1 uses role="tooltip" — supplementary, non-interactive
• If your card contains interactive elements (links, buttons), consider using popover/1 instead, which has role="dialog" and a proper focus trap