Tooltip은 왜 가려질까 — Portal과 getBoundingClientRect로 설계하는 스타일 불변 툴팁

툴팁은 UI에서 가장 흔하게 쓰이는 컴포넌트 중 하나지만, 의외로 "망가지기 쉬운" 컴포넌트이기도 합니다.

단순한 정적 페이지에서는 position: absolute와 CSS ::before만으로도 잘 동작합니다. 하지만 실제 앱에서는 카드 안에, 모달 안에, 애니메이션 컨테이너 안에 들어가면서 조용히 잘리거나, 다른 요소 뒤로 숨거나, 예상치 못한 위치에 나타나는 문제가 생깁니다.

이 글은 툴팁이 가려지는 세 가지 근본 원인을 분석하고, 어떤 부모 구조를 갖든 항상 같은 형태로 렌더되는 툴팁을 설계하는 방법을 다룹니다.

1. 툴팁이 보이지 않는 세 가지 원인

원인 1 — overflow: hidden

position: absolute인 요소는 가장 가까운 positioned 조상을 기준으로 배치됩니다. 그런데 그 조상이 overflow: hidden을 갖고 있으면, 박스 경계를 벗어나는 모든 자식은 잘립니다.

┌───────────────────────────────┐  ← overflow: hidden
│                               │
│  [버튼]                        │
│    ┌──────────────────┐       │
│    │ ✂ 잘린 툴팁       │       │
│ ─ ─│─ ─ ─ ─ ─ ─ ─ ─ ─│─ ─ ─ │  ← 이 선 아래는 보이지 않음
└───────────────────────────────┘

원인 2 — transform이 만드는 containing block 함정

overflow: hidden을 피하기 위해 position: fixed로 바꾸는 것은 좋은 시도입니다. 하지만 한 가지 함정이 더 있습니다.

CSS 명세에 따르면, transform / filter / will-change / perspective 속성이 있는 요소는 새로운 containing block을 형성합니다. position: fixed인 자식 요소는 viewport가 아닌 이 요소를 기준으로 배치됩니다.

“

transform: translateX(0)처럼 아무런 시각적 변화가 없는 선언 하나가, 하위 모든 position: fixed 요소의 기준점을 바꿔버립니다.

다크모드 전환 애니메이션, 슬라이드 인/아웃, 카드 hover lift 효과 — 모두 transform을 사용하기 때문에 이 함정에 빠지기 쉽습니다.

원인 3 — z-index Stacking Context

z-index는 같은 stacking context 안에서만 비교됩니다. 서로 다른 stacking context에 속한 요소들의 z-index는 직접 비교가 불가능합니다.

2. 세 문제를 한 번에 해결하는 방법: Portal

세 원인 모두 공통된 해결책이 있습니다. 툴팁을 DOM 트리에서 탈출시키는 것입니다.

React의 createPortal은 컴포넌트를 원래 부모 트리가 아닌 다른 DOM 노드에 렌더합니다. 보통 document.body를 대상으로 사용합니다.

import { createPortal } from "react-dom";

function TooltipPortal({ children }: { children: React.ReactNode }) {
// document.body 직하에 마운트 → 어떤 조상 스타일에도 영향받지 않음
return createPortal(children, document.body);
}

document.body 직하에 마운트된 요소는 다음 세 가지가 보장됩니다.

3. getBoundingClientRect()로 위치 계산하기

Portal로 렌더된 툴팁은 document.body 소속이기 때문에 트리거 요소의 위치를 CSS로 알 수 없습니다. JS로 좌표를 계산해 주입해야 합니다.

getBoundingClientRect()는 DOM 요소의 뷰포트 기준 좌표를 반환하는 메서드입니다.

viewport (브라우저 창)
┌────────────────────────────────────────┐
│ │
│ ↑ rect.top (px) │
│ ┌──────────────────┐ │
│ │ │ rect.height │
│ │ element │ │
│ └──────────────────┘ │
│ ↓ rect.bottom │
│ │
│ ←rect.left→ ←rect.right→ │
│ ←── rect.width ───→ │
└────────────────────────────────────────┘

반환되는 DOMRect 객체의 주요 프로퍼티:

position: fixed도 뷰포트 기준으로 배치되기 때문에, getBoundingClientRect()의 좌표를 바로 left, top에 사용할 수 있습니다. 스크롤 오프셋을 따로 더할 필요가 없습니다.

const absoluteTop  = rect.top  + window.scrollY;
const absoluteLeft = rect.left + window.scrollX;

트리거 중앙 위에 배치하는 좌표 공식

function useTooltip() {
  const [pos, setPos] = useState({ x: 0, y: 0, visible: false });

const show = useCallback((e: React.MouseEvent<HTMLElement>, text: string) => {
const rect = e.currentTarget.getBoundingClientRect();

    setPos({
      x: rect.left + rect.width / 2,  // 수평 중앙
      y: rect.top,                    // 요소 상단 (툴팁은 transform으로 위로 올림)
      visible: true,
    });

}, []);

const hide = useCallback(
() => setPos(p => ({ ...p, visible: false })),
[]
);

return { pos, show, hide };
}

좌표를 fixed 요소에 적용할 때는 transform으로 수평 중앙 정렬과 위쪽 배치를 동시에 처리합니다.

<div style={{
  position: "fixed",
  left: pos.x,
  top: pos.y,
  transform: "translate(-50%, -100%)",  // 수평 중앙 + 요소 위로 이동
  marginTop: "-8px",                    // 요소와의 여백
  pointerEvents: "none",                // 툴팁이 hover를 가로채지 않도록
}} />

4. 뷰포트 경계 감지 — Flip Logic

화면 상단에 있는 요소에 툴팁을 올리면 뷰포트 밖으로 잘려나갈 수 있습니다. 공간이 부족하면 반대 방향으로 flip하는 로직이 필요합니다.

const TOOLTIP_HEIGHT = 36;
const GAP = 8;
const hasSpaceAbove = rect.top > TOOLTIP_HEIGHT + GAP;

const placement: "top" | "bottom" = hasSpaceAbove ? "top" : "bottom";

const y = placement === "top"
  ? rect.top               // 요소 위 → transform으로 올림
  : rect.bottom + GAP;     // 요소 아래 → 그대로 내림

const TOOLTIP_WIDTH = 200;
const x = Math.max(
  TOOLTIP_WIDTH / 2,
  Math.min(rawX, window.innerWidth - TOOLTIP_WIDTH / 2)
);

5. ref 없이 위치를 얻는 방법

Portal 기반 툴팁에서 트리거 요소의 위치를 얻기 위해 반드시 ref가 필요하지는 않습니다.

<button
  onMouseEnter={(e) => {
    const rect = e.currentTarget.getBoundingClientRect();
    show(rect, "툴팁 텍스트");
  }}
  onMouseLeave={hide}
>
  hover me
</button>

6. 스타일 불변성 설계 원칙

Portal로 DOM 위치 문제를 해결했더라도, 툴팁의 스타일이 부모에 오염되지 않도록 설계해야 합니다.

.tooltip {
  /* 상속될 수 있는 속성들을 명시적으로 재선언 */
  font-family: system-ui, -apple-system, sans-serif;
  font-size: 13px;
  font-weight: 500;
  line-height: 1.5;
  color: #f1f5f9;
  letter-spacing: normal;
  text-align: left;
  text-transform: none;
  white-space: nowrap;
}

7. 컴포넌트 파일 구조

완성된 툴팁 컴포넌트의 파일 구조 예시입니다.

각 파일의 역할을 분리하면 다음과 같습니다.

8. 완성된 구조 정리

핵심 요약