Floating

Tooltip

hover 또는 focus 시 보조 정보를 표시하는 툴팁. 화살표와 딜레이를 지원합니다.

설치

npm install @woon-ui/tooltip

import { Tooltip } from '@woon-ui/tooltip'
import '@woon-ui/tooltip/css'

개요

import { Tooltip } from '@woon-ui/tooltip'

Tooltip은 플러그인 등록 없이 바로 사용할 수 있습니다. hover와 focus 모두에 반응하며, @floating-ui/react 기반으로 위치를 자동 계산합니다.

기본 사용법

import { Tooltip } from '@woon-ui/tooltip'

<Tooltip.Root>
  <Tooltip.Trigger>
    <button>hover me</button>
  </Tooltip.Trigger>
  <Tooltip.Content>툴팁 텍스트</Tooltip.Content>
</Tooltip.Root>

Preview

컴파운드 컴포넌트

Tooltip.Root

위치와 딜레이 등 모든 설정을 Root에서 관리합니다.

Prop	Type	Default
open	boolean	—
제어 모드: 열림 상태
defaultOpen	boolean	`false`
비제어 모드: 초기 열림 여부
onOpenChange	(open: boolean) => void	—
열림 상태 변경 콜백
side	'top'\|'right'\|'bottom'\|'left'	`'top'`
툴팁이 표시되는 방향
align	'start'\|'center'\|'end'	`'center'`
트리거를 기준으로 한 정렬
sideOffset	number	`6`
트리거와의 간격 (px)
alignOffset	number	`0`
정렬 방향 오프셋 (px)
avoidCollisions	boolean	`true`
화면 밖으로 넘어갈 때 자동으로 반대쪽으로 뒤집습니다
collisionPadding	number	`8`
화면 가장자리 여백 (px)
delay	number\|{ open?: number; close?: number }	`500`
열림/닫힘 딜레이 (ms). 숫자로 전달하면 open 딜레이만 적용되고 close는 0입니다.

Tooltip.Trigger

asChild를 사용하면 Trigger의 기능을 자식 요소에 위임합니다.

Tooltip.Content

표준 div 속성을 지원합니다. style, className 등을 직접 전달할 수 있습니다.

Tooltip.Arrow

@floating-ui/react의 FloatingArrow를 래핑합니다. Tooltip.Content 안에 넣으면 위치가 자동으로 계산됩니다.

Prop	Type	Default
width	number	`12`
화살표 너비 (px)
height	number	`6`
화살표 높이 (px)
fill	string	—
화살표 채우기 색상
stroke	string	—
화살표 테두리 색상
strokeWidth	number	—
테두리 두께
tipRadius	number	—
화살표 꼭짓점 둥글기

딜레이

delay prop으로 열림 딜레이를 설정합니다. 기본값은 500ms입니다.

// 숫자: open 딜레이 (close는 0)
<Tooltip.Root delay={200}>

// 객체: open/close 개별 설정
<Tooltip.Root delay={{ open: 200, close: 100 }}>

// 즉시 열림
<Tooltip.Root delay={0}>

Preview

화살표

Tooltip.Arrow를 Tooltip.Content 안에 넣으면 화살표가 표시됩니다.

<Tooltip.Content>
  툴팁 텍스트
  <Tooltip.Arrow />
</Tooltip.Content>

// 색상 변경
<Tooltip.Arrow fill="#333" stroke="#333" />

// 둥근 꼭짓점
<Tooltip.Arrow tipRadius={2} />

// 크기 변경
<Tooltip.Arrow width={16} height={8} />

Preview

위치 설정

side와 align을 조합해 12가지 방향을 지정할 수 있습니다. Popover와 동일한 API를 사용합니다.

Preview

제어 모드

open과 onOpenChange를 전달하면 외부에서 상태를 제어할 수 있습니다.

const [open, setOpen] = useState(false)

<Tooltip.Root open={open} onOpenChange={setOpen}>
  <Tooltip.Trigger>hover me</Tooltip.Trigger>
  <Tooltip.Content>제어된 툴팁</Tooltip.Content>
</Tooltip.Root>

스타일

@woon-ui/tooltip/css로 기본 스타일이 적용됩니다. 특정 값만 바꾸려면 선택자로 override하세요.

[data-woon-tooltip-content] {
  background: #3b0764;
  border-radius: 4px;
}

완전히 교체하려면 @woon-ui/react/css import를 제거하고 아래 CSS를 복사해서 수정하세요.

[data-woon-tooltip-floating] { z-index: 600; pointer-events: none; }
[data-woon-tooltip-arrow]    { z-index: 1; }

/* 화살표 border 보정 */
[data-woon-tooltip-content][data-side="top"]    [data-woon-tooltip-arrow] { top:    calc(100% - 2px) !important; }
[data-woon-tooltip-content][data-side="bottom"] [data-woon-tooltip-arrow] { bottom: calc(100% - 2px) !important; }
[data-woon-tooltip-content][data-side="left"]   [data-woon-tooltip-arrow] { left:   calc(100% - 2px) !important; }
[data-woon-tooltip-content][data-side="right"]  [data-woon-tooltip-arrow] { right:  calc(100% - 2px) !important; }

[data-woon-tooltip-content],
[data-woon-tooltip-content] *,
[data-woon-tooltip-content] *::before,
[data-woon-tooltip-content] *::after {
  box-sizing: border-box;
}

[data-woon-tooltip-content] {
  width: max-content;
  max-width: 20rem;
  padding: 0.375rem 0.625rem;
  background: #18181b;
  color: #fafafa;
  border-radius: 6px;
  font-family: system-ui, -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;
  font-size: 0.8125rem;
  line-height: 1.4;
}

[data-woon-tooltip-content][data-state='open'] {
  animation: woon-tooltip-in 120ms cubic-bezier(0.16, 1, 0.3, 1);
}

@keyframes woon-tooltip-in {
  from { opacity: 0; scale: 0.96; }
  to   { opacity: 1; scale: 1; }
}

@media (prefers-reduced-motion) {
  [data-woon-tooltip-content] { animation: none !important; }
}

접근성

Content에 role="tooltip" 자동 적용
Trigger에 aria-describedby 자동 연결
hover와 focus 모두에 반응 (키보드 접근성)
pointer가 떠나거나 blur 시 닫힘

Note

Tooltip은 보조 정보용입니다. 중요한 정보는 항상 화면에 직접 표시하세요.

data 속성

속성	대상	값
`data-woon-tooltip-content`	Content	—
`data-state`	Content	`"open"`
`data-side`	Content	`"top"` `"right"` `"bottom"` `"left"`
`data-align`	Content	`"start"` `"center"` `"end"`
`data-woon-tooltip-arrow`	Arrow	—

[data-woon-tooltip-content] {
  background: #333;
  color: white;
  padding: 6px 10px;
  border-radius: 4px;
  font-size: 13px;
}