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 · 아이콘 버튼을 트리거로 사용할 수 있습니다.
클릭 트리거
trigger="click"으로 클릭 시 말풍선을 토글합니다. 말풍선 우측 상단에 닫기 버튼이 기본 제공됩니다.
배치
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 | 타입 | 기본값 | 설명 |
|---|---|---|---|
content | string | — | 말풍선 텍스트. children으로 대체 |
placement | 'top' | 'top-start' | 'top-end' | 'left' | 'right' | 'start' | 'end' | — | tooltip_placement-* |
size | 'sm' | 'md' | 'lg' | md | tooltip_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-* |
open | boolean | false | 열림 (is-open) |
inverse | boolean | false | 어두운 배경 (tooltip_inverse) |
noArrow | boolean | false | 화살표 숨김 |
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' | center | target·mixed 시 트리거 내 화살표 위치 |
disabled | boolean | false | 트리거 비활성 |
trigger | 'hover' | 'click' | hover | click 시 data-tooltip-trigger="click" |
interactive | boolean | true | false면 data-tooltip 미부여 |
closable | boolean | click 시 true | 말풍선 닫기 버튼. hover 트리거는 기본 false |
closeLabel | string | 닫기 | 닫기 버튼 aria-label |
triggerContent | ReactNode | — | 트리거 UI (Vue #trigger 슬롯 대응) |
className | string | — | tooltip 루트에 추가 클래스 |
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-align | JS 연동 |
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-lg | 16rem · 12rem · 20rem | 말풍선 최대 너비 |
--tooltip-padding-x · --tooltip-padding-y · --tooltip-font-size | — | 패딩·글자 |
--tooltip-offset · --tooltip-offset-sm · --tooltip-offset-md · --tooltip-offset-lg | var(--space-xs) · … | 전 방향 간격 토큰 |
--tooltip-offset-top · --tooltip-offset-right · --tooltip-offset-bottom · --tooltip-offset-left | offset 상속 | 방향별 간격 (배치에 따라 적용) |
--tooltip-arrow-size | 6px | 화살표 크기 |
--tooltip-panel-radius · --tooltip-arrow-edge-inset | 6px · calc | 말풍선 라운드·화살표 가장자리 여백 |
--tooltip-arrow-position | — | target 기준 시 트리거 중앙 위치(px) |
--tooltip-inverse-bg · --tooltip-inverse-text | — | inverse 스킨 |