Tooltip

Tooltip

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

기본

Tooltip과 triggerContent로 트리거와 말풍선을 구성합니다. content prop으로 텍스트를 넣고, 호버·포커스 시 tooltip_bubble이 표시됩니다.

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

슬롯

content prop 대신 children으로 말풍선 텍스트를 넣을 수 있습니다.

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

열린 상태

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

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

크기

size prop(sm · md · lg)으로 패딩·글자 크기·최대 너비를 조절합니다.

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

간격

offset prop(none · sm · md · lg)으로 전 방향 간격을, offsetTop 등으로 방향별 간격을 조절합니다.

전 방향 동일

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

방향별 (offset-* · placement)

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

인라인

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

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

트리거 유형

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

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

클릭 트리거

trigger="click"으로 클릭 시 말풍선을 토글합니다. 말풍선 우측 상단에 닫기 버튼이 기본 제공됩니다.

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

배치

placement prop으로 말풍선 위치를 조정합니다. 기본은 트리거 아래·가운데 정렬입니다.

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

역색

inverse prop으로 어두운 배경의 말풍선을 표시합니다.

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

비활성 트리거

비활성 버튼은 래퍼에 tabindex를 주어 pointer-events가 막힌 요소에도 설명을 제공합니다.

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

화살표 기준

arrowAnchor(content · target · mixed)와 panelAlign, arrowTargetAlign으로 말풍선·화살표를 독립 조합합니다.

기준 비교

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

target — 좌 · 가운데 · 우

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

mixed — 말풍선 가운데 · 화살표 조합

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

화살표 없음

noArrow prop으로 tooltip_arrow를 숨깁니다.

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

마크업

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

// 기본 — content prop
<Tooltip
  content="짧은 도움말 텍스트입니다."
  triggerContent={<Button className="tooltip_trigger" variant="outline" label="마우스 오버" />}
/>

// children
<Tooltip triggerContent={<Button className="tooltip_trigger" variant="outline" label="슬롯 예시" />}>
  짧은 도움말 텍스트입니다.
</Tooltip>

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

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

// 배치 · 스킨 · 간격
<Tooltip
  placement="top"
  inverse
  offset="lg"
  content="어두운 배경의 말풍선입니다."
  triggerContent={<Button className="tooltip_trigger" variant="ghost" label="역색 Tooltip" />}
/>

// 간격 — 방향별
<Tooltip
  placement="right"
  offsetRight="lg"
  content="트리거 오른쪽 배치 시 offsetRight가 적용됩니다."
  triggerContent={<Button className="tooltip_trigger" variant="outline" label="offset-right" />}
/>

// 혼합 — 말풍선 가운데 · 화살표 오른쪽
<Tooltip
  arrowAnchor="mixed"
  panelAlign="center"
  arrowTargetAlign="right"
  open
  content="말풍선은 가운데, 화살표는 트리거 오른쪽입니다."
  triggerContent={<Button className="tooltip_trigger" variant="outline" size="sm" label="S" />}
/>

API · Props

Prop타입기본값설명
contentstring말풍선 텍스트. children으로 대체
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
offsetTop · offsetRight · offsetBottom · offsetLeft'none' | 'sm' | 'md' | 'lg'방향별 간격. tooltip_offset-top-* 등 · --tooltip-offset-*
openbooleanfalse열림 (is-open)
inversebooleanfalse어두운 배경 (tooltip_inverse)
noArrowbooleanfalse화살표 숨김
arrowAnchor'content' | 'target' | 'mixed'content화살표 기준. target=화살표만, mixed=말풍선·화살표 독립
panelAlign'start' | 'center' | 'end'center말풍선 교차축 정렬. tooltip_panel-align-* · data-panel-align
arrowTargetAlign'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
closeLabelstring닫기닫기 버튼 aria-label
triggerContentReactNode트리거 UI (Vue #trigger 슬롯 대응)
classNamestringtooltip 루트에 추가 클래스

API · Children

Children설명
triggerContent트리거 요소 (Vue #trigger 슬롯 대응)
children말풍선 텍스트 (content 대체, Vue default 슬롯 대응)

클래스 · 속성

React 컴포넌트가 렌더하는 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 스킨