Components

Tooltips

Docs

API 사용가이드입니다. 위치·간격 프리뷰는 Overview를 참고하세요.

API

children을 Tooltip으로 감싸면 hover·focus 시 content가 표시됩니다. position(상/하/좌/우)과 offset(px)으로 위치를 제어합니다. 세밀한 제어가 필요하면 TooltipRoot · TooltipTrigger · TooltipContent 합성 API를 사용하세요.

import { Tooltip } from "@/components/tooltip";

<Tooltip content="계정 설정" position="top" offset={8}>
  <Button>설정</Button>
</Tooltip>

// 합성 API
import {
  TooltipRoot,
  TooltipTrigger,
  TooltipContent,
} from "@/components/tooltip";

<TooltipRoot>
  <TooltipTrigger asChild>
    <Button>설정</Button>
  </TooltipTrigger>
  <TooltipContent position="bottom" offset={4}>
    계정 설정
  </TooltipContent>
</TooltipRoot>

Props

Name	Type	Default	Description
`children`Required	`React.ReactNode`	—	툴팁을 붙일 대상 요소. asChild로 감싸 이벤트를 위임합니다.
`content`Required	`React.ReactNode`	—	툴팁 내용.
`position`	`"top" \| "bottom" \| "left" \| "right"`	`"top"`	트리거 기준 표시 방향. 화면 경계에 걸리면 자동으로 반전됩니다.
`offset`	`number`	`8`	트리거와 툴팁 사이 간격(px).
`withArrow`	`boolean`	`true`	꼬리 화살표 표시 여부.
`color`	`string`	`var(--surface-inverse)`	배경색. CSS 색상값 또는 var(--token)을 전달합니다. 화살표에도 적용됩니다.
`textColor`	`string`	`var(--text-inverse)`	텍스트색. CSS 색상값 또는 var(--token)을 전달합니다.
`disabled`	`boolean`	`false`	true면 툴팁을 표시하지 않고 children만 렌더링합니다.
`delayDuration`	`number`	`300`	hover 후 표시까지 지연(ms).
`open / defaultOpen`	`boolean`	—	제어/비제어 열림 상태.
`className`	`string`	—	TooltipContent 추가 클래스.

Events

Name	Signature	Description
`onOpenChange`	`(open: boolean) => void`	열림 상태가 바뀔 때 호출됩니다.

Notes

소비 앱 필수: React 19, Tailwind CSS v4, ClaBi tokens.css(+ @theme 매핑), clsx, @radix-ui/react-tooltip.
clsx 패키지가 필수입니다. className 병합에 import { clsx } from "clsx" 를 사용합니다.
내부적으로 @radix-ui/react-tooltip을 사용합니다. 소비 앱에도 해당 패키지가 필요합니다.
hover·키보드 focus 표시, ESC 닫기, 화면 경계 자동 반전, Portal 렌더링은 Radix가 처리합니다.
children은 ref와 이벤트를 받을 수 있는 요소여야 합니다(버튼·링크 등). 텍스트만 감쌀 때는 span으로 감싸세요.
터치 전용 환경에서는 hover가 없으므로 중요한 정보를 툴팁에만 두지 마세요.