HoverCard

링크나 요소에 마우스를 올렸을 때 추가 정보를 미리 보여주는 카드 컴포넌트

개요

HoverCard 컴포넌트는 base-ui의 PreviewCard Primitive를 기반으로, 트리거 요소에 호버 시 풍부한 콘텐츠를 담은 카드를 팝업으로 표시합니다. 사용자 프로필 미리보기, 링크 요약 등에 활용합니다.

주요 특징

✅ 호버 트리거: 마우스 호버 시 자동으로 카드 표시, 지연 시간 제어 가능
✅ 위치 제어: side, align, 오프셋으로 카드 위치 조정
✅ Portal 렌더링: 콘텐츠가 Portal로 렌더링되어 오버플로우에 안전
✅ 애니메이션: 열림/닫힘 시 fade·zoom·slide 애니메이션 기본 적용
✅ 접근성: base-ui 기반 ARIA 속성 및 포커스 관리
✅ 디자인 토큰: 테마 커스터마이징 지원

사용 예시

기본

Preview

@vortex

위치 제어

side와 align으로 카드가 표시될 위치를 지정합니다.


<HoverCard>
  <HoverCardTrigger>Hover me</HoverCardTrigger>
  <HoverCardContent side="top" align="start">
    위쪽(start 정렬)에 표시됩니다.
  </HoverCardContent>
</HoverCard>

지연 시간 제어

delay와 closeDelay로 열림/닫힘 지연 시간(ms)을 조정합니다.


<HoverCard delay={200} closeDelay={100}>
  <HoverCardTrigger>Hover me</HoverCardTrigger>
  <HoverCardContent>200ms 후에 열리고 100ms 후에 닫힙니다.</HoverCardContent>
</HoverCard>

API Reference

base-ui PreviewCard.Root의 props를 그대로 전달합니다.

Prop	Type	Default	Description
`open`	`boolean`	-	제어 모드의 열림 상태
`defaultOpen`	`boolean`	`false`	비제어 모드의 초기 열림 상태
`onOpenChange`	`(open: boolean) => void`	-	열림 상태 변경 콜백
`delay`	`number`	-	호버 후 열리기까지 지연 시간(ms)
`closeDelay`	`number`	-	호버 해제 후 닫히기까지 지연 시간(ms)

HoverCardTrigger Props

base-ui PreviewCard.Trigger의 props를 전달합니다. 트리거가 되는 요소를 감쌉니다.

HoverCardContent Props

Prop	Type	Default	Description
`side`	`"top" \| "bottom" \| "left" \| "right" \| ...`	`"bottom"`	카드가 표시될 방향
`sideOffset`	`number`	`4`	트리거와의 거리(px)
`align`	`"start" \| "center" \| "end"`	`"center"`	트리거 기준 정렬
`alignOffset`	`number`	`4`	정렬 기준 오프셋(px)
`className`	`string`	-	추가 CSS 클래스

기본 사용법


import {
  HoverCard,
  HoverCardTrigger,
  HoverCardContent,
} from "@vortex/ui-foundation"
 
;<HoverCard>
  <HoverCardTrigger>Hover me</HoverCardTrigger>
  <HoverCardContent>미리보기 콘텐츠</HoverCardContent>
</HoverCard>

접근성

base-ui PreviewCard 기반으로 트리거와 팝업 간 aria-describedby 연결 및 포커스 관리가 자동 처리됩니다.
트리거에 키보드 포커스 시에도 카드가 열리도록 지원합니다.
✅ 트리거는 링크나 버튼 등 포커스 가능한 요소를 사용하세요.
❌ 카드 안에 필수 상호작용 콘텐츠만 두지 마세요. 복잡한 상호작용은 Popover 또는 Dialog를 사용하세요.