Tooltip
요소에 붙는 짧은 설명이다. 기본은 트리거 옆에 붙고, hasPortal 로 body 로 내보낼 수 있다.
import { Tooltip } from "@nui-kit/react";
// 서브패스로 좁힐 때
import { Tooltip } from "@nui-kit/react/tooltip";
import "@nui-kit/react/styles/tooltip.css"; // 온디맨드일 때import { Tooltip } from "@nui-kit/react";
<Tooltip content="삭제한 항목은 되돌릴 수 없습니다">
<IconButton aria-label="삭제"><DelIcon /></IconButton>
</Tooltip>기본
긴 설명 보기
<Tooltip content="삭제하면 되돌릴 수 없습니다">
<IconButton aria-label="삭제"><DelIcon /></IconButton>
</Tooltip>hover 하거나 Tab 으로 포커스해보세요
잘리는 부모에서 — hasPortal
말풍선은 트리거 옆 absolute 라 overflow: hidden 인 조상에서 잘린다. hasPortal 을 켜면 body 로 내보내고 스크롤과 창 크기 변화를 따라간다.
<Tooltip content="설명" hasPortal>…</Tooltip>같은 상자 안 — 왼쪽은 잘리고 오른쪽은 안 잘린다
<LayerPopup …>
<Tooltip content="설명" hasPortal>…</Tooltip>
</LayerPopup>팝업 안 — 아래 줄은 defaultOpen 이다. 왼쪽은 패널에 잘려 아무것도 안 보이고, 오른쪽은 패널 밖으로 나온다
위치
placement 6종. 트리거 기준 위/아래 × 좌/중앙/우다.
<Tooltip content="설명" placement="bottomLeft">…</Tooltip>placement — 각 버튼에 hover 해보세요
제어 모드
open 을 주면 열림 상태를 소비자가 소유한다. 온보딩 안내처럼 hover 와 무관하게 띄워야 할 때 쓴다.
대상 요소
<Tooltip content="설명" open={isOpen} onOpenChange={setIsOpen}>…</Tooltip>open prop 으로 직접 제어
비활성
<Tooltip content="설명" disabled>…</Tooltip>disabled — 열려 있어도 즉시 닫힌다
접근성
- 열려 있는 동안 트리거에
aria-describedby가 연결된다 — 마우스를 쓰지 않는 사용자도 내용을 들을 수 있다 - hover 뿐 아니라 포커스로도 열린다 (키보드 사용자)
- ESC 로 닫힌다
- 터치에서는 탭으로 열고 닫는다 (KRDS 가이드 659 · 662쪽). 바깥을 탭해도 닫힌다. 탭은 트리거의 원래 동작을 막지 않으므로 아이콘 버튼이면 버튼도 함께 눌린다
- 버블은
role="tooltip"이다
툴팁에 중요한 정보를 담지 않는다. 터치 기기에서는 hover 가 없어 열기 어렵고, 사라지면 다시 볼 방법이 마땅치 않다. 꼭 필요한 설명은
Field.Description 으로 화면에 남긴다.기본은 트리거 옆
absolute 라 조상에 overflow: hidden 이 있으면 잘린다. hasPortal 을 켜면 body 로 나가 잘리지 않고, 스크롤·리사이즈를 따라간다. 잘림만 없앤다 — 뷰포트 밖으로 밀리는 것은 그대로다. 화면 가장자리에서는 placement 를 골라야 한다.커스터마이징
색은 컴포넌트별로 열지 않는다. 한 곳만 바꾸려면 className 을, 화면 전체를 바꾸려면 브랜드 프리셋을 쓴다.
className 으로 배경을 바꿀 때는 버블과 화살표를 함께 바꾼다. 둘이 같은 색을 쓰므로 하나만 바꾸면 화살표가 따로 논다.| 컴포넌트 | 변수 | 기본값 | 비고 |
|---|---|---|---|
| Tooltip | --nui-tooltip--max-width | min(17.5rem, calc(100vw - 2rem)) | — |
| --nui-tooltip--radius | var(--nui-radius-1_5) | — |
API
| 이름 | 타입 | 기본값 | 설명 |
|---|---|---|---|
children * | ReactNode | — | — |
content * | ReactNode | — | — |
className | string | — | — |
defaultOpen | boolean | false | — |
disabled | boolean | false | — |
hasPortal | boolean | false | 말풍선을 `body` 로 내보낸다. `overflow: hidden` 조상(팝업 패널 등)에서 잘리지 않게 하려면 켠다. 기본값은 `false` — 제자리 배치가 기본이다. ⚠️ 잘림만 없앤다. 뷰포트 밖으로 밀리는 것은 그대로이므로 가장자리에서는 `placement` 를 소비자가 골라야 한다. |
onOpenChange | (nextOpen: boolean) => void | — | — |
open | boolean | — | 제어 모드. 주면 열림 상태를 소비자가 소유한다 |
placement | TooltipPlacement | "topCenter" | — |
TooltipProps 에서 자동 생성됨 (components/Tooltip/Tooltip.tsx).