7onicDESIGN SYSTEM

Tooltip

요소에 호버하거나 포커스했을 때 보조 정보를 표시하는 오버레이 컴포넌트입니다. 버튼이나 아이콘 설명, 단축키 표시 등에 적합합니다.

2
Variants
2
Sizes
4
Sides
Radix
Base

Playground

Preview
defaultTop
Variant
Size
Side
Options
<Tooltip>
  <Tooltip.Trigger asChild>
    <Button variant="outline">Hover me</Button>
  </Tooltip.Trigger>
  <Tooltip.Content>
    Tooltip text
  </Tooltip.Content>
</Tooltip>

Variants

Default
어두운 배경에 그림자를 적용한 기본 variant. 부유하는 느낌의 일반적인 보조 정보에 사용합니다.
아이콘 설명, 힌트
Inverted
글라스모피즘 배경을 적용한 variant. 배경 블러가 있는 세련된 스타일입니다.
리치 UI, 밝은 배경

Sizes

sm
폰트12px
패딩4px 10px
default
폰트13px
패딩6px 12px

Features

Side Placement

4방향(top, right, bottom, left)에 배치할 수 있습니다. 기본값은 top입니다.

<Tooltip.Content side="top">Top</Tooltip.Content>
<Tooltip.Content side="right">Right</Tooltip.Content>
<Tooltip.Content side="bottom">Bottom</Tooltip.Content>
<Tooltip.Content side="left">Left</Tooltip.Content>

Arrow

showArrow로 트리거를 가리키는 화살표 표시를 제어합니다. 기본값은 표시입니다.

{/* With arrow (default) */}
<Tooltip.Content>With arrow</Tooltip.Content>

{/* Without arrow */}
<Tooltip.Content showArrow={false}>No arrow</Tooltip.Content>

Alignment

align으로 트리거에 대한 정렬을 조정합니다.

<Tooltip.Content align="start">Start</Tooltip.Content>
<Tooltip.Content align="center">Center</Tooltip.Content>
<Tooltip.Content align="end">End</Tooltip.Content>

Provider

Tooltip.Provider로 전역 딜레이 설정을 관리합니다. skipDelayDuration을 통해 연속 호버 시 다음 툴팁이 즉시 표시됩니다.

<Tooltip.Provider delayDuration={400} skipDelayDuration={200}>
  {/* All tooltips inside share these delay settings */}
  <Tooltip>
    <Tooltip.Trigger asChild>
      <Button>First</Button>
    </Tooltip.Trigger>
    <Tooltip.Content>First tooltip</Tooltip.Content>
  </Tooltip>
</Tooltip.Provider>

API

Component Structure

Tooltip— Radix Tooltip
.Trigger.ContentProps.Arrow.Portal.ProviderProps

Props

Tooltip (Root)

openundefined
boolean

툴팁 표시 상태 (제어 모드)

defaultOpenfalse
boolean

초기 표시 상태 (비제어 모드)

onOpenChangeundefined
(open: boolean) => void

표시 상태가 변경될 때의 콜백

delayDuration200
number

호버에서 표시까지의 딜레이 (ms)

disableHoverableContentfalse
boolean

콘텐츠 위에 호버해도 표시 유지 안 함

Tooltip.Content

variant"default"
"default" | "inverted"

외관 variant. default: 어두운 배경+그림자, inverted: 글라스모피즘

size"default"
"sm" | "default"

텍스트 크기

side"top"
"top" | "right" | "bottom" | "left"

표시 방향

sideOffset6
number

트리거와의 거리 (px)

align"center"
"start" | "center" | "end"

트리거에 대한 정렬

showArrowtrue
boolean

방향 화살표 표시

Tooltip.Provider

delayDuration700
number

전역 호버 딜레이 (ms)

skipDelayDuration300
number

연속 호버 시 딜레이 스킵 시간 (ms)

disableHoverableContentfalse
boolean

전역적으로 콘텐츠 호버 유지 비활성화

Anatomy

2
Tooltip text
3
sideOffset: 6px
1
Button
1
Trigger
호버 대상 요소
2
Content
툴팁 본체
3
Arrow
방향 표시 화살표

Best Practices

✓

권장

  • ✓아이콘 버튼과 액션의 보조 설명에 Tooltip을 사용합니다
  • ✓텍스트는 짧고 간결하게 유지합니다 (1~2줄 이내)
  • ✓키보드 단축키 표시에 Tooltip을 활용합니다
  • ✓잘린 텍스트의 전체 내용을 표시할 때 Tooltip을 사용합니다
✕

지양

  • ✕필수 정보를 Tooltip에만 넣지 않습니다. 항상 표시되는 텍스트에도 작성합니다
  • ✕링크, 버튼 등 인터랙티브 콘텐츠를 Tooltip에 넣지 않습니다. Popover를 사용합니다
  • ✕긴 단락이나 리치 콘텐츠를 Tooltip에 넣지 않습니다
  • ✕터치 기기 사용자에게 필요한 정보를 Tooltip에만 제공하지 않습니다

Tooltip vs Popover

비슷한 플로팅 UI이지만 용도와 인터랙션이 다릅니다.

트리거

Tooltip: 호버 / 포커스

Popover: 클릭

콘텐츠

Tooltip: 텍스트만 (짧은 보조 정보)

Popover: 리치 (폼, 버튼, 링크)

인터랙션

Tooltip: 없음 (읽기만 가능)

Popover: 있음 (조작 가능)

기본 방향

Tooltip: top (읽기 흐름을 방해하지 않음)

Popover: bottom (자연스러운 위→아래 조작)

닫기

Tooltip: 호버 해제 시 자동

Popover: 외부 클릭 / Esc / 닫기 버튼

ARIA

Tooltip: role="tooltip"

Popover: aria-expanded + aria-controls

Tooltip은 호버 시 표시되는 짧은 보조 텍스트에 사용합니다. 링크나 버튼 같은 인터랙티브 콘텐츠가 필요하면 Popover를 사용합니다.

Accessibility

키보드 조작

Tab트리거에 포커스 시 표시 (딜레이 없음)
Esc툴팁 닫기

ARIA / WCAG

  • role="tooltip" Radix가 자동으로 부여
  • aria-describedby 자동 연결
  • WCAG 1.4.13: 콘텐츠 호버 시 유지
  • 자동 충돌 회피 (화면 밖 넘침 방지)