HoverCard

HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.

Installation

npm install @astryxdesign/core@0.7.1 @astryxdesign/theme-neutral@0.7.1 @stylexjs/stylex@0.19.0

Requires React 19+, base CSS and a Theme provider. See Setup.

Hover Card

HoverCard shows additional information when the user hovers or focuses a trigger element. Use it for profile cards, link summaries, or inline definitions where the user needs more context without navigating away.

Usage guidance

• Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow.
• Provide a dashed underline on text triggers so users know the element is hoverable.
• Use the hook API (useHoverCard) when you need more control over timing or placement.
• Leave touchTrigger on auto so a tap opens the card on triggers that do nothing else, and stays out of the way on triggers that perform an action.
• Avoid: Place critical actions or required information inside a hover card; users may miss content that only appears on hover.
• Avoid: Use a hover card when a simple Tooltip or Popover would suffice.
• Avoid: Use a HoverCard for content the user must interact with; it disappears when the cursor leaves.
• Prefer placing HoverCard in a block context rather than directly in a <p>, heading, or link. Those placements are supported when necessary through a corrective portal, but the DOM and tab order may differ.

Theming API

{
  "targets": [
    {
      "className": "astryx-hover-card"
    }
  ],
  "vars": [
    {
      "name": "--_hovercard-radius",
      "description": "Border radius of the hover card",
      "default": "var(--radius-container)",
      "private": true
    }
  ],
  "derived": [
    {
      "property": "borderRadius",
      "vars": [
        "--_hovercard-radius"
      ]
    }
  ]
}

Hover Card

Component wrapper for hover card display: a richer, larger overlay triggered on hover or focus.

Anatomy

• Trigger: The element that opens the hover card on hover or focus: a button, link, or inline text.
• Card: The floating overlay with the preview content, anchored to the trigger.
• Body: The main content area: profile info, link summary, or any rich content.
• Actions: Optional buttons inside the card for follow-up actions like Follow or Message.

useHoverCard

Headless hook for hover-triggered floating cards. Builds on useLayer with hover/focus intent detection, configurable delays, safe hover behavior, and accessible aria-describedby linking. Use for rich previews on hover when you need full control over the trigger or rendered content.

Parameters

Returns

[
  {
    "name": "ref",
    "type": "RefCallback<HTMLElement>",
    "description": "Combined ref that sets both position and interaction on the same trigger element."
  },
  {
    "name": "positionRef",
    "type": "RefCallback<HTMLElement>",
    "description": "Ref for the positioning anchor element. Use when position and interaction live on different elements."
  },
  {
    "name": "interactionRef",
    "type": "RefCallback<HTMLElement>",
    "description": "Ref for the hover/focus interaction element. Use with positionRef for split trigger patterns."
  },
  {
    "name": "anchorId",
    "type": "string",
    "description": "CSS anchor name for advanced positioning cases."
  },
  {
    "name": "describedBy",
    "type": "string",
    "description": "ID to compose into aria-describedby on the trigger."
  },
  {
    "name": "renderHoverCard",
    "type": "(children: ReactNode, props?: Omit<ContextRenderProps, 'positioning'>) => ReactNode",
    "description": "Render function for the anchor-positioned hover card content. The positioning opt-out is excluded: the hover card always derives its position from placement/alignment."
  },
  {
    "name": "show",
    "type": "() => void",
    "description": "Imperatively show the hover card immediately."
  },
  {
    "name": "hide",
    "type": "() => void",
    "description": "Imperatively hide the hover card immediately."
  }
]

Usage guidance

• Use for rich content previews such as user profiles, entity summaries, and link previews.
• Prefer the HoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns.
• Avoid: Use for simple text hints: use Tooltip or useTooltip instead.

Examples

• Hover Card: A hover card that shows a user profile preview when hovering over a trigger button. Starts open for preview.
• useHoverCard — Profile Preview: Custom profile preview using useHoverCard with direct trigger and render control.
• HoverCard — Definition: Shows a term definition on hover within a paragraph. Use for technical terms, jargon, or concepts that some readers may not know, like a glossary built into the text.
• HoverCard — Link Preview: Shows a page summary when hovering a link: title, description, and URL. Use for documentation links, article references, or any URL where a preview helps the user decide whether to click.
• HoverCard — Profile Preview: Shows a user profile summary on hover with name, role, and bio. Use on usernames, avatars, or mentions to let users preview a profile without navigating away.

Complete example dependencies

Some examples import optional icons. The per-example install command in the examples list identifies exactly what that example needs. For all examples on this page:

npm install @heroicons/react@2.2.0