Tooltip
먼저 보고, 그다음 계약을 읽습니다
hover/focus 로 뜨는 가벼운 힌트 — 인터랙티브 컨텐츠는 담지 않는다 (Radix Tooltip 기반).
Component intent의도와 경계 읽기
단일 라인~2·3줄 짧은 설명용. 반전 색(어두운 bg·밝은 텍스트) 표면에 pointer-events:none 이라 마우스로 잡을 수 없다(그 자리는 Popover/HoverCard). 키보드 focus 로도 등장해 접근성을 지키고, 기본 portal 이라 overflow:hidden 부모에 갇히지 않는다. TooltipProvider(앱 루트 1회, delay 글로벌 공유)·Tooltip(Root)·TooltipTrigger·TooltipContent 를 조합한다.
예제
SSOT에 등록된 실제 API 기준 snippet입니다. standalone 배지만 독립 실행 단위이며, fragment는 주변 state·handler 문맥을 생략합니다.
import { TooltipProvider, Tooltip, TooltipTrigger, TooltipContent,} from "@axe/ui";import { Button } from "@axe/ui";// Provider 는 앱 루트에 1회 두는 것을 권장<TooltipProvider> <Tooltip> <TooltipTrigger asChild> <Button variant="ghost">?</Button> </TooltipTrigger> <TooltipContent side="top">이 값은 자동 계산됩니다</TooltipContent> </Tooltip></TooltipProvider>import { Tooltip, TooltipTrigger, TooltipContent,} from "@axe/ui";import { Button } from "@axe/ui";<Tooltip> <TooltipTrigger asChild> <Button aria-label="삭제" variant="ghost"> <TrashIcon /> </Button> </TooltipTrigger> <TooltipContent side="bottom" withArrow={false}>삭제</TooltipContent></Tooltip>Props
TSX 소스가 진실입니다. 주요 export 컴포넌트의 public API만 노출합니다.
| 이름 | 타입 | 필수 | 기본값 | 설명 |
|---|---|---|---|---|
delayDuration | number | — | 200 | TooltipProvider — hover 후 등장까지 지연(ms). 개별 Tooltip(Root) 에서 override 가능. |
skipDelayDuration | number | — | 200 | TooltipProvider — 한 툴팁을 닫은 뒤 이 시간 내 다른 트리거로 이동하면 지연 없이 즉시 등장. |
open | boolean | — | — | 열림 상태 (controlled). Tooltip(Root) prop. |
onOpenChange | (open: boolean) => void | — | — | 열림/닫힘 콜백 (Root). |
sideOffset | number | — | 6 | TooltipContent 와 트리거 사이 간격(px). |
withPortal | boolean | — | true | TooltipContent 를 portal 로 띄울지 — overflow:hidden 부모 탈출. |
withArrow | boolean | — | true | 트리거를 가리키는 화살표 표시 여부. |
...rest | 각 Radix Tooltip.* props | — | — | Provider(disableHoverableContent)·Trigger(asChild)·Content(side/align/collisionPadding) 등 각 파트는 대응 Radix 컴포넌트 props 를 그대로 전파. |
.axe-* 클래스 계약
React 밖에서도 같은 표면을 그리는 공개 계약입니다. stable은 minor 버전 안에서 이름을 바꾸지 않습니다.
| 클래스 | 안정성 | 용도 |
|---|---|---|
.axe-tooltip__content | stable | 툴팁 표면(반전 색·pointer-events:none·small radius). |
.axe-tooltip__arrow | stable | 트리거를 가리키는 화살표(Radix Arrow). |
접근성
키보드, ARIA, 구현 노트를 함께 검토합니다.
- 트리거로 Tab 이동(키보드 focus)만으로도 툴팁 등장
- Esc 로 닫기
Radix 가 트리거에 aria-describedby 로 툴팁 컨텐츠를 연결하고 컨텐츠에 role=tooltip 을 부여. hover 와 키보드 focus 두 경로로 등장한다. content 는 pointer-events:none 이라 마우스로 잡을 수 없다.
TooltipProvider 로 delay 를 글로벌 공유한다. 첫 툴팁은 짧게 진입하고, 연속 툴팁은 skipDelayDuration 안에서 delay와 재등장 애니메이션을 모두 생략해 즉시 전환한다. 네이티브 disabled 버튼은 이벤트를 안 내보내 툴팁이 안 뜨니, 필요하면 트리거를 감싸는 span 등에 씌운다. prefers-reduced-motion 시 애니메이션 제거.