Tooltip

한눈에#

트리거 위에 뜨는 짧은 텍스트 힌트입니다 — hover는 400ms 지연, focus는 즉시 표시하며 role="tooltip" + aria-describedby로 연결됩니다.

클립보드에 복사합니다복사

• 짧은 텍스트 힌트
• hover 400ms · focus 즉시
• role=tooltip + aria-describedby
• Escape 닫기·Hoverable

hover 또는 Tab 포커스로 실제 힌트를 띄워 보세요:

복사

사용 시점#

아이콘 버튼·축약 라벨에 짧은 보조 설명을 덧붙이면 Tooltip — 링크·버튼 등 상호작용이 필요하면 Popover입니다.

플레이그라운드#

컨트롤로 props를 조작하면 미리보기와 코드가 실시간 갱신됩니다.

Tooltip를 직접 조작해 보세요

속성·테마·토큰을 바꾸고 React·Flutter 코드를 확인하는 풀스크린 빌더로 엽니다.

빌더 열기→

플레이그라운드는 넓은 작업 영역이 필요해 웹·태블릿에서 편집할 수 있어요.

변형#

variant로 두 형태를 지원합니다 (ADR-012 B-P1).

• plain(기본) — 짧은 텍스트 힌트(content 한 줄)
• rich — title(제목) + content(본문) 구조 카드. 더 넓고 좌측 정렬

색은 텍스트/배경 토큰을 반전해(color.text 배경 + color.bg 글자) 라이트/다크 모두 대비를 확보합니다. 버블은 hover 가능(pointer-events: auto)하지만 role="tooltip"은 텍스트 보조 설명 용도이므로, 버튼·링크 등 인터랙티브 콘텐츠가 필요하면 Popover를 쓰세요(rich도 텍스트 전용).

floating(기본 false)은 버블을 document.body로 포털(position: fixed)해 오버플로 스크롤 컨테이너(표·사이드바 등) 안에서 잘리지 않게 합니다. 공통 geometry solver가 앵커·버블·뷰포트 크기를 재서 top/bottom/left/right를 자동 배치하고, 가장자리에서는 버블을 안쪽으로 shift하면서 화살표는 앵커를 가리키도록 clamp합니다. 인-플로우가 기본이라 평상시엔 끌 필요가 없고, 클리핑되는 컨테이너 안에서만 켜세요(기본값이라 기존 사용처는 영향 없음).

크기#

단일 크기입니다 — caption 타이포 + 최대 폭 16rem(긴 문구는 줄바꿈).

상태#

• Hover — HOVER_SHOW_DELAY_MS(400ms) 지연 후 표시 — 스치는 마우스 과발화 방지
• Focus — 지연 없이 즉시 표시
• 호버 유지 — leave 후 HOVER_HIDE_GRACE_MS(120ms) 유예를 둬, 포인터가 트리거→버블로 넘어가면 버블 진입이 유예를 취소합니다 — 내용 위에 머물 수 있습니다(WCAG 1.4.13)
• 숨김 — 트리거·버블 양쪽에서 벗어난 뒤(유예 경과) · blur · Escape

Props#

접근성#

• role="tooltip" + 표시 중 트리거에 aria-describedby 주입 — 트리거가 단일 요소일 때만 가능하므로 단일 포커서블 요소를 권장합니다
• 키보드 사용자는 포커스만으로 즉시 볼 수 있습니다(지연 없음)
• Escape로 닫기 — 포커스/호버 위치 무관(WCAG 1.4.13 Dismissable)
• Hoverable(WCAG 1.4.13) — 버블은 pointer-events: auto라, 트리거에서 버블로 포인터를 옮겨도 사라지지 않습니다(leave는 짧은 유예 후 숨김)
• 툴팁은 이름이 아니라 설명입니다 — 아이콘 버튼의 접근성 이름은 aria-label로 따로 부여하세요
• 등장 모션은 prefers-reduced-motion 존중

토큰#

component 토큰 없이 semantic을 직접 소비합니다(신설 기준 §4 미충족).