shadcn-syntax-popover-tooltip-hovercard

name	shadcn-syntax-popover-tooltip-hovercard
description	Use when picking between Popover, Tooltip, and HoverCard for any floating panel above the page : a click-to-open form panel, a short hover hint on an icon button, a rich preview card that appears when the cursor lingers on a user mention, a date picker container, a filter popover, or any other "small panel anchored to an element" UX. Use when debugging why a Tooltip never appears (missing `TooltipProvider` at the app root), why a HoverCard flickers as the cursor passes over an avatar list (zero `openDelay`), why a Tooltip works on desktop but is invisible on iPad (Radix hides Tooltip on touch by design), why focus jumps to the body after a Popover closes (`modal={true}` focus-trap on a non-modal panel), or why a Popover refuses to close when controlled (passing `open` without `onOpenChange`). Use when choosing which primitive to install for an emoji-picker, a colour-picker, a notification preview, a profile-card preview on hover, a help-text hint on a form label, or a confirm-action popover. Prevents the canonical floating-panel mismatches : reaching for Tooltip when the content is interactive (links / buttons / inputs inside a Tooltip lose keyboard navigation and disappear on touch devices), reaching for HoverCard when the trigger is itself interactive AND the content must be reachable by keyboard-only users (hover-only is an a11y violation), reaching for Popover when a one-line non-interactive hint would suffice (Popover forces a click and steals focus on open), forgetting to wrap the React tree in `<TooltipProvider>` so every `<Tooltip>` is a silent no-op, nesting a Popover inside a Dialog without re-portalling so the popover renders behind the Dialog overlay, and setting `modal={true}` on a Popover that contains a `<form>` Submit so focus restoration fights the form-state machine on close. Covers the three Radix-backed primitives shipped in shadcn ui new-york-v4 (`apps/v4/registry/new-york-v4/ui/{popover,tooltip,hover-card}.tsx`), including the full export surface (Popover : Popover / PopoverTrigger / PopoverContent / PopoverAnchor / PopoverHeader / PopoverTitle / PopoverDescription, Tooltip : TooltipProvider / Tooltip / TooltipTrigger / TooltipContent, HoverCard : HoverCard / HoverCardTrigger / HoverCardContent), the shadcn-specific default overrides (TooltipProvider `delayDuration={0}` shadcn default vs Radix-700 underlying default, PopoverContent `sideOffset={4}`, TooltipContent `sideOffset={0}`, HoverCardContent `sideOffset={4}`, all three `align="center"`), the controlled-state pattern (`open` + `onOpenChange`), the `modal` prop on Popover (focus-trap on vs off), the touch-device behaviour matrix (Tooltip hidden, HoverCard tap-to-open, Popover always-on), the accessibility matrix (`aria-describedby` for Tooltip, `aria-haspopup` for HoverCard, focus management for Popover), and the `"use client"` requirement that applies to all three. Keywords: shadcn popover, shadcn tooltip, shadcn hover card, shadcn hovercard, Popover vs Tooltip, Tooltip vs HoverCard, HoverCard vs Popover, when to use popover, when to use tooltip, when to use hovercard, click popup, hover content, hover popup, floating panel, TooltipProvider, TooltipProvider missing, tooltip not showing, tooltip not appearing, tooltip silent fail, why is my tooltip blank, tooltip not appearing on touch, tooltip on mobile, tooltip on iPad, tooltip hidden touch device, delayDuration, openDelay, closeDelay, hover-card delay, hover card flicker, hover-card instant, PopoverAnchor, Popover modal, modal popover, modal=true Popover, popover focus trap, popover form submit focus, popover with form, popover with input, popover with date picker, popover with colour picker, popover with emoji picker, tooltip on icon button, tooltip on disabled button, hover card user profile, hover card profile preview, hover card mention, hover card avatar preview, Tooltip with interactive content, HoverCard keyboard accessibility, Popover behind Dialog, Popover inside Dialog, Popover z-index, Portal Popover, controlled Popover, controlled Tooltip, controlled HoverCard, open and onOpenCha…
license	MIT
compatibility	Designed for Claude Code. Requires shadcn ui evergreen-2026.
metadata	{"author":"OpenAEC-Foundation","version":"1.0"}

shadcn ui : Popover vs Tooltip vs HoverCard

Three Radix-backed floating-panel primitives ship in shadcn ui new-york-v4. They look similar (a panel anchored to a trigger) but solve three disjoint UX problems. Picking the wrong one breaks keyboard navigation, touch users, screen readers, or all three at once. This skill is a decision tree, not three API surfaces stacked together. The full prop tables live in references/methods.md; the working recipes live in references/examples.md; the failure modes live in references/anti-patterns.md.

The single decision

Is the panel content interactive (inputs, links, buttons, anything
keyboard-focusable)?
├─ NO  -> Is the hint a short, plain-text label (one sentence max)?
│         ├─ YES -> Tooltip
│         └─ NO  -> Popover (open it on click, even for read-only content)
└─ YES -> Should the panel appear on hover, or on click?
          ├─ HOVER (and the trigger is keyboard-reachable too) -> HoverCard
          └─ CLICK                                              -> Popover

Three additional gates ALWAYS override the table above :

1. If the trigger is on a touch device and the content is critical : NEVER Tooltip. Tooltip is hidden on touch by Radix design. Use Popover instead.
2. If the content contains a <form> with a Submit button : NEVER Tooltip and NEVER HoverCard. Use Popover; both Tooltip and HoverCard close on pointer-leave, which races the form submission.
3. If the content is keyboard-only-reachable via the trigger : NEVER Tooltip and NEVER HoverCard. Tooltip cannot host interactive elements; HoverCard is hover-only and fails WCAG 2.1.1 Keyboard. Use Popover.

Decision Matrix at a glance

Need	Primitive	Trigger	Content	a11y
One-line label on icon button	Tooltip	hover / focus	text only	aria-describedby
One-line label on disabled button	Tooltip (wrap a <span>)	hover / focus	text only	aria-describedby
Rich profile preview on mention	HoverCard	hover / focus	text + image + links	aria-haspopup
Date picker calendar	Popover	click	Calendar component	focus moves into panel
Colour picker	Popover