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.
ts
| Guidance | Practices |
|---|---|
| Do | Keep content supplementary; hover cards should enhance understanding without blocking the primary workflow. |
| Do | Provide a dashed underline on text triggers so users know the element is hoverable. |
| Do | Use the hook API (useHoverCard) when you need more control over timing or placement. |
| Don't | Place critical actions or required information inside a hover card; users may miss content that only appears on hover. |
| Don't | Use a hover card when a simple Tooltip or Popover would suffice. |
| Don't | Use a HoverCard for content the user must interact with; it disappears when the cursor leaves. |
| Don't | Nest a HoverCard whose content has block elements directly inside phrasing-only contexts such as a <p>, <label>, or heading. The card renders inline, so block content there is invalid HTML the browser reparents. Wrap the surrounding text in a block element (e.g. a <div>) instead. |
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.
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.
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.