Tooltip

Tooltip

호버·포커스 시 트리거 근처에 짧은 설명을 띄우는 Tooltip 컴포넌트입니다. 용어 정의·아이콘 버튼 보조 설명·비활성 요소 이유 안내 등에 사용하며, role="tooltip" · aria-describedby로 접근성을 보장합니다.

기본

Tooltip과 #trigger 슬롯으로 트리거와 말풍선을 구성합니다. content prop으로 텍스트를 넣고, 호버·포커스 시 tooltip_bubble이 표시됩니다. data-tooltip · aria-describedby로 JS·접근성을 연동합니다.

짧은 도움말 텍스트입니다.

슬롯

content prop 대신 default 슬롯으로 말풍선 텍스트를 넣을 수 있습니다. tooltip_bubble 안에 직접 본문을 배치합니다.

짧은 도움말 텍스트입니다.

열린 상태

open prop과 is-open 클래스로 말풍선이 표시된 상태를 정적으로 표현합니다.

정적 데모용 열린 상태입니다.

크기

size prop(sm · md · lg)으로 패딩·글자 크기·최대 너비를 조절합니다. tooltip_sm · tooltip_lg 클래스와 대응됩니다.

작은 말풍선기본 크기 말풍선큰 말풍선 — 조금 더 긴 설명을 담을 수 있습니다.

간격

offset prop(none · sm · md · lg)으로 전 방향 간격을, offset-top · offset-right · offset-bottom · offset-left로 방향별 간격을 조절합니다. 배치에 따라 해당 방향 토큰이 트리거↔말풍선 사이에 적용됩니다.

전 방향 동일

간격 없음좁은 간격기본 간격넓은 간격

방향별 (offset-* · placement)

위쪽 간격
왼쪽 간격
아래쪽 간격
오른쪽 간격

인라인

문장 안의 링크·텍스트에 Tooltip을 붙여 용어를 설명할 수 있습니다.

결제 시 에스크로구매자가 상품 수령을 확인할 때까지 대금을 안전하게 보관하는 결제 방식입니다. 서비스를 이용할 수 있습니다.

트리거 유형

Button · Link · 아이콘 버튼을 트리거로 사용할 수 있습니다.

버튼 트리거 예시입니다.Link 트리거링크 스타일 트리거입니다.아이콘 전용 트리거입니다.

클릭 트리거

trigger="click"으로 클릭 시 말풍선을 토글합니다. data-tooltip-trigger="click"과 동일하며, 접근성을 위해 tooltip_close 닫기 버튼이 기본 제공됩니다.

클릭으로 열고 닫는 Tooltip입니다.

배치

placement prop(top · top-start · top-end · start · end · left · right)으로 말풍선 위치를 조정합니다. tooltip_placement-* 클래스와 대응되며, 기본은 트리거 아래·가운데 정렬입니다.

트리거 위
트리거 왼쪽
트리거 아래 · 가운데
트리거 오른쪽
위쪽 왼쪽 정렬아래쪽 왼쪽 정렬아래쪽 오른쪽 정렬

역색

inverse prop으로 어두운 배경의 말풍선을 표시합니다. tooltip_inverse 클래스와 대응됩니다.

어두운 배경의 말풍선입니다.

비활성 트리거

비활성 버튼은 포커스 가능한 span으로 감싸 pointer-events가 막힌 요소에도 설명을 제공합니다.

필수 항목을 모두 입력해야 제출할 수 있습니다.

화살표 기준

arrow-anchor(content · target · mixed)와 panel-align(start · center · end), arrow-target-align으로 말풍선·화살표를 독립 조합합니다. target은 말풍선 CSS·화살표 JS, mixed는 말풍선·화살표 모두 JS로 트리거 기준 배치합니다.

기준 비교

패널이 트리거보다 넓을 때 화살표는 말풍선 패딩 기준입니다.패널이 트리거보다 넓을 때 화살표가 트리거 중앙을 가리킵니다.

target — 좌 · 가운데 · 우 (아래 배치)

트리거 왼쪽을 가리킵니다.트리거 가운데를 가리킵니다.트리거 오른쪽을 가리킵니다.

target — 위 · 가운데 · 아래 (왼쪽 배치)

트리거 위쪽을 가리킵니다.트리거 가운데를 가리킵니다.트리거 아래쪽을 가리킵니다.

mixed — 말풍선 가운데 · 화살표 좌 · 가운데 · 우

말풍선 가운데, 화살표 왼쪽.
말풍선·화살표 모두 가운데.
말풍선 가운데, 화살표 오른쪽.

mixed — 말풍선 왼쪽 · 화살표 조합

말풍선 왼쪽, 화살표 왼쪽.
말풍선 왼쪽, 화살표 가운데.
말풍선 왼쪽, 화살표 오른쪽.

mixed — 말풍선 오른쪽 · 화살표 조합

말풍선 오른쪽, 화살표 왼쪽.
말풍선 오른쪽, 화살표 가운데.
말풍선 오른쪽, 화살표 오른쪽.

화살표 없음

no-arrow prop으로 tooltip_arrow를 숨깁니다. tooltip_no-arrow 클래스와 대응됩니다.

화살표가 표시되지 않는 말풍선입니다.

마크업

Tooltip 컴포넌트로 트리거와 말풍선을 감쌉니다. content prop 또는 default 슬롯으로 텍스트를 넣고, trigger · placement · inverse prop과 #trigger 슬롯으로 데모와 동일하게 구성할 수 있습니다.

<!-- 기본 — content prop -->
<Tooltip content="짧은 도움말 텍스트입니다.">
  <template #trigger>
    <Button variant="outline" label="마우스 오버" />
  </template>
</Tooltip>

<!-- default 슬롯 -->
<Tooltip>
  <template #trigger>
    <Button variant="outline" label="슬롯 예시" />
  </template>
  짧은 도움말 텍스트입니다.
</Tooltip>

<!-- 클릭 트리거 — tooltip_close 기본 제공 -->
<Tooltip trigger="click" content="클릭으로 열고 닫는 Tooltip입니다.">
  <template #trigger>
    <Button variant="outline" label="클릭하여 보기" />
  </template>
</Tooltip>

<!-- 비활성 버튼 래핑 -->
<Tooltip content="필수 항목을 모두 입력해야 제출할 수 있습니다.">
  <template #trigger>
    <span tabindex="0">
      <Button variant="filled" color="primary" label="제출 불가" disabled />
    </span>
  </template>
</Tooltip>

<!-- 배치 · 스킨 · 간격 -->
<Tooltip placement="top" inverse offset="lg" content="어두운 배경의 말풍선입니다.">
  <template #trigger>
    <Button variant="ghost" label="역색 Tooltip" />
  </template>
</Tooltip>

<!-- 간격 — 방향별 -->
<Tooltip placement="right" offset-right="lg" content="트리거 오른쪽 배치 시 offset-right가 적용됩니다.">
  <template #trigger>
    <Button variant="outline" label="offset-right" />
  </template>
</Tooltip>

<!-- 혼합 — 말풍선 가운데 · 화살표 오른쪽 -->
<Tooltip arrow-anchor="mixed" panel-align="center" arrow-target-align="right" open content="말풍선은 가운데, 화살표는 트리거 오른쪽입니다.">
  <template #trigger>
    <Button variant="outline" size="sm" label="S" />
  </template>
</Tooltip>

API · Props

Prop타입기본값설명
contentstring말풍선 텍스트. default 슬롯으로 대체
placement'top' | 'top-start' | 'top-end' | 'left' | 'right' | 'start' | 'end'tooltip_placement-*
size'sm' | 'md' | 'lg'mdtooltip_sm · tooltip_lg
offset'none' | 'sm' | 'md' | 'lg'md전 방향 동일 간격. tooltip_offset-* · --tooltip-offset
offset-top · offset-right · offset-bottom · offset-left'none' | 'sm' | 'md' | 'lg'방향별 간격. tooltip_offset-top-* 등 · --tooltip-offset-*
openbooleanfalse열림 (is-open)
inversebooleanfalse어두운 배경 (tooltip_inverse)
no-arrowbooleanfalse화살표 숨김
arrow-anchor'content' | 'target' | 'mixed'content화살표 기준. target=화살표만, mixed=말풍선·화살표 독립
panel-align'start' | 'center' | 'end'center말풍선 교차축 정렬. tooltip_panel-align-* · data-panel-align
arrow-target-align'center' | 'top' | 'bottom' | 'left' | 'right' | 'start' | 'end'centertarget·mixed 시 트리거 내 화살표 위치
disabledbooleanfalse트리거 비활성
trigger'hover' | 'click'hoverclick 시 data-tooltip-trigger="click"
interactivebooleantruefalse면 data-tooltip 미부여
closablebooleanclick 시 true말풍선 닫기 버튼. hover 트리거는 기본 false
close-labelstring닫기닫기 버튼 aria-label

API · Slots

슬롯설명
trigger트리거 요소
default말풍선 텍스트 (content 대체)

클래스 · 속성

Vue 컴포넌트가 렌더하는 OOCSS 클래스입니다. HTML 마크업으로 직접 작성할 때 동일하게 조합합니다.

클래스설명
tooltip · tooltip_trigger · tooltip_bubble · tooltip_arrow · tooltip_close루트·트리거·말풍선
tooltip_sm · tooltip_lg · tooltip_inverse · tooltip_no-arrow크기·스킨
tooltip_panel-align-start · tooltip_panel-align-end말풍선 교차축 정렬
tooltip_arrow-anchor-target · tooltip_arrow-anchor-mixed화살표·혼합 기준
tooltip_offset-none · tooltip_offset-sm · tooltip_offset-lg전 방향 간격
tooltip_offset-top-* · tooltip_offset-right-* · tooltip_offset-bottom-* · tooltip_offset-left-*방향별 간격
tooltip_placement-*배치 변형
data-tooltip · data-tooltip-trigger · data-tooltip-close · data-panel-align · data-arrow-target-alignJS 연동
is-open · is-disabled · hidden상태
role="tooltip" · aria-describedby · aria-expanded접근성

닫기: tooltip_close · 바깥 클릭 · data-tooltip-close · Esc. 클릭 트리거는 말풍선 우측 상단에 닫기 버튼이 기본 제공됩니다.

디자인 토큰

토큰기본값설명
--tooltip-max-width · --tooltip-max-width-sm · --tooltip-max-width-lg16rem · 12rem · 20rem말풍선 최대 너비
--tooltip-padding-x · --tooltip-padding-y · --tooltip-font-size패딩·글자
--tooltip-offset · --tooltip-offset-sm · --tooltip-offset-md · --tooltip-offset-lgvar(--space-xs) · …전 방향 간격 토큰
--tooltip-offset-top · --tooltip-offset-right · --tooltip-offset-bottom · --tooltip-offset-leftoffset 상속방향별 간격 (배치에 따라 적용)
--tooltip-arrow-size6px화살표 크기
--tooltip-panel-radius · --tooltip-arrow-edge-inset6px · calc말풍선 라운드·화살표 가장자리 여백
--tooltip-arrow-positiontarget 기준 시 트리거 중앙 위치(px)
--tooltip-inverse-bg · --tooltip-inverse-textinverse 스킨