Tooltip

요소에 마우스를 올렸을 때 추가 정보를 표시하는 컴포넌트

개요

Tooltip 컴포넌트는 base-ui의 Tooltip Primitive를 기반으로 트리거 요소에 호버 또는 포커스 시 보조 정보를 표시합니다. 화살표가 포함된 팝업이 Portal로 렌더링되며, 위치와 정렬을 세밀하게 제어할 수 있습니다.

주요 특징

• ✅ 위치 제어: side(top/right/bottom/left), align(start/center/end) 지원
• ✅ 오프셋 조정: sideOffset, alignOffset으로 거리 미세 조정
• ✅ 화살표 포함: 트리거를 가리키는 Arrow 자동 렌더링
• ✅ 애니메이션: 열림/닫힘 시 fade + zoom + slide 애니메이션
• ✅ Provider 내장: Tooltip이 TooltipProvider를 자동으로 포함 (delay 기본 0)
• ✅ 디자인 토큰: 테마 커스터마이징 지원

사용 예시

기본

트리거에 마우스를 올리면 툴팁이 표시됩니다.

<Tooltip>
  <TooltipTrigger render={<Button variant="outline">마우스를 올려보세요</Button>} />
  <TooltipContent>라이브러리에 추가</TooltipContent>
</Tooltip>

위치 지정

side prop으로 툴팁이 표시될 위치를 지정합니다.

<TooltipContent side="top">위쪽 툴팁</TooltipContent>
<TooltipContent side="right">오른쪽 툴팁</TooltipContent>
<TooltipContent side="bottom">아래쪽 툴팁</TooltipContent>
<TooltipContent side="left">왼쪽 툴팁</TooltipContent>

아이콘 버튼

레이블이 없는 아이콘 버튼에 툴팁으로 기능을 설명합니다.

<Tooltip>
  <TooltipTrigger
    render={
      <Button variant="outline" size="icon-sm">
        <Plus />
      </Button>
    }
  />
  <TooltipContent>항목 추가</TooltipContent>
</Tooltip>

API Reference

Tooltip (Root)

base-ui Tooltip.Root의 props를 지원하며, 내부적으로 TooltipProvider를 포함합니다.

TooltipTrigger

TooltipContent

TooltipProvider

여러 Tooltip의 동작을 공통으로 제어할 때 사용합니다. (Tooltip 단독 사용 시 자동 포함)

기본 사용법

import {
  Tooltip,
  TooltipTrigger,
  TooltipContent,
} from "@vortex/ui-foundation"
 
<Tooltip>
  <TooltipTrigger render={<Button variant="outline">Hover</Button>} />
  <TooltipContent side="top" sideOffset={4}>
    툴팁 내용
  </TooltipContent>
</Tooltip>

접근성

시맨틱 마크업

• base-ui Tooltip 기반으로 트리거와 툴팁이 aria-describedby로 연결
• 키보드 포커스 시에도 툴팁이 표시되어 포인터 없이 정보 확인 가능

권장 사항

• ✅ 아이콘만 있는 버튼에는 반드시 툴팁으로 기능 설명 제공
• ✅ 툴팁 내용은 짧은 보조 정보로 제한
• ❌ 필수 정보나 상호작용 요소를 툴팁 안에 넣지 않기

관련 컴포넌트

• Button: 툴팁 트리거로 자주 사용
• Sidebar: 접힌 메뉴 버튼의 툴팁 지원
• Badge: 상태를 상시 표시하는 대안