An open source design system that's fully customizable and agent ready
TypeScript
// Copyright (c) Meta Platforms, Inc. and affiliates.
/** @type {import('@astryxdesign/cli/authoring').HookDoc} */
export const docs = {
name: 'useHoverCard',
displayName: 'useHoverCard',
group: 'HoverCard',
keywords: [
'hovercard',
'hover',
'preview',
'card',
'tooltip',
'popup',
'floating',
'anchor',
],
params: [
{
name: 'placement',
type: "'above' | 'below' | 'start' | 'end'",
description:
"Position relative to the trigger. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
default: "'above'",
},
{
name: 'alignment',
type: "'start' | 'center' | 'end'",
description:
"Alignment along the placement axis. Logical: start/end resolve against the popover\'s own inherited direction (RTL mirrors in pure CSS).",
default: "'center'",
},
{
name: 'delay',
type: 'number',
description:
'Delay before showing the hover card on hover, in milliseconds.',
default: '300',
},
{
name: 'hideDelay',
type: 'number',
description:
'Delay before hiding after mouse or focus leaves, in milliseconds.',
default: '200',
},
{
name: 'focusTrigger',
type: "'auto' | 'always' | 'never'",
description:
'When focus should open the hover card. auto opens when the trigger itself takes focus, or focus lands inside a trigger that is focusable at that moment, so a roving-tabindex member opens when the arrow keys reach it.',
default: "'auto'",
},
{
name: 'touchTrigger',
type: "'auto' | 'tap' | 'none'",
description:
'What a tap does where there is no hover. auto opens on tap unless the trigger performs an action of its own (an aria-disabled control performs none); tap always opens; none never opens on touch.',
default: "'auto'",
},
{
name: 'isEnabled',
type: 'boolean',
description: 'Whether hover and focus triggers are enabled.',
default: 'true',
},
{
name: 'label',
type: 'string',
description:
'Accessible name for the hover card popup. When provided, the popup is exposed as a named role="dialog"; when omitted, it falls back to role="group" (a group may validly be unnamed).',
},
{
name: 'isOpen',
type: 'boolean',
description:
'Controlled open state. true force-shows, false force-hides, undefined lets hover/focus manage visibility.',
},
{
name: 'isDefaultOpen',
type: 'boolean',
description: 'Whether the hover card should be shown on mount.',
default: 'false',
},
{
name: 'onShow',
type: '() => void',
description: 'Callback fired when the hover card becomes visible.',
},
{
name: 'onHide',
type: '() => void',
description: 'Callback fired when the hover card is hidden.',
},
],
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: {
description:
'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.',
bestPractices: [
{
guidance: true,
description:
'Use for rich content previews such as user profiles, entity summaries, and link previews.',
},
{
guidance: true,
description:
'Prefer the HoverCard component for standard trigger-content pairs; use the hook for custom trigger patterns.',
},
{
guidance: false,
description:
'Use for simple text hints: use Tooltip or useTooltip instead.',
},
],
},
relatedComponents: ['HoverCard', 'Tooltip', 'Popover'],
relatedHooks: ['useLayer', 'useTooltip', 'usePopover'],
importPath: '@astryxdesign/core/HoverCard',
category: 'interaction',
};
/** @type {import('@astryxdesign/cli/authoring').HookTranslationDoc} */
export const docsDense = {
description:
'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
paramDescriptions: {
placement:
"position relative to trigger. logical: start/end follow the popover's inherited direction (RTL mirrors).",
alignment:
"alignment along placement axis. logical: start/end follow the popover's inherited direction (RTL mirrors).",
delay: 'show delay in ms.',
hideDelay: 'hide delay after mouse/focus leave in ms.',
focusTrigger:
'when focus opens hover card; auto = focus on the trigger, or inside a trigger focusable when focus arrives.',
touchTrigger:
'tap behavior with no hover; auto = tap unless trigger acts, tap = always, none = never.',
isEnabled: 'whether hover/focus triggers are enabled.',
label:
'accessible name for popup. with label: named role="dialog"; without: role="group".',
isOpen:
'controlled open state: true force-show, false force-hide, undefined unmanaged.',
isDefaultOpen: 'show on mount.',
onShow: 'fires when hover card becomes visible.',
onHide: 'fires when hover card hides.',
},
returnDescriptions: {
ref: 'combined position + interaction ref.',
positionRef: 'position anchor ref.',
interactionRef: 'hover/focus interaction ref.',
anchorId: 'CSS anchor name.',
describedBy: 'ID for aria-describedby.',
renderHoverCard: 'renders anchor-positioned hover card content.',
show: 'show immediately.',
hide: 'hide immediately.',
},
usage: {
description:
'Headless hover-triggered floating cards. Builds on useLayer w/ hover/focus intent, delays, safe hover behavior, aria-describedby. Use for rich previews when trigger/content rendering needs full control.',
bestPractices: [
{
guidance: true,
description:
'Use for rich previews: profiles, entity summaries, link previews.',
},
{
guidance: true,
description:
'Prefer HoverCard for standard trigger-content pairs; use hook for custom trigger patterns.',
},
{
guidance: false,
description:
'Use for simple text hints: use Tooltip / useTooltip instead.',
},
],
},
};