🧠 React Portal로 모달을 띄우는 이유: 겉만 모달이면 안 되는 이유

React 프로젝트를 하다 보면 모달은 정말 자주 쓰입니다.

그런데, 단순히 "모달 UI"만 있다고 해서 진짜 '모달답게' 동작하는 건 아니더라고요.

최근 제가 겪었던 사례를 공유드리며,

React Portal이 왜 필요한지, 그리고 기존 방식에서 어떤 문제가 있었는지 정리해보려 합니다.

---

🎯 문제 상황: 모달이 상단을 못 덮어요?

대표자 선택 모달을 띄우는 기능을 만들면서,

같은 Modal 컴포넌트를 사용하는데도, 어떤 모달은 정상적으로 화면 전체를 덮고, 어떤 모달은 상단 네비게이션이 뚫리는 현상을 경험했습니다.

모달 종류	동작 여부
✅ 부서 선택 모달	정상 작동 (전체 오버레이)
❌ 사용자 선택 모달	상단 메뉴 뚫림 현상 발생

분명히 같은 모달 컴포넌트를 사용했는데 왜 그럴까?

---

🔍 원인 분석: DOM 계층과 z-index의 배신

문제는 모달이 렌더링되는 위치에 있었습니다.

사용자 선택 모달은 form 내부 깊은 위치에서 렌더링되었고,

이 경우 부모 컴포넌트들의 position: relative, overflow: hidden, z-index 설정이 영향을 주게 됩니다.

즉, 시각적으로는 '모달처럼' 보여도,
실제로는 상위 DOM 구조에 갇힌, 제약이 많은 모달이었던 거죠.

---

💡 해결 방법: React Portal 도입

React에서는 이런 문제를 해결하기 위한 공식적인 기능이 있습니다.

React Portal: 부모 DOM 바깥에 자식을 렌더링할 수 있는 기능입니다.

✨ React Portal이 좋은 이유

장점	설명
✅ DOM 구조와 상관없이 최상단 렌더링	document.body 아래에 직접 삽입되므로 부모 구조 무관
✅ 완전한 오버레이 구현 가능	position: fixed로 화면 전체 덮기 완벽 보장
✅ z-index 충돌 최소화	특정 트리 내 z-index 순서 문제 회피 가능
✅ 모달, 토스트, 드롭다운 등에 적합	시각적 독립성이 중요한 컴포넌트에 최적

---

🔧 적용 예시 코드

tsx
복사편집
return ReactDOM.createPortal(modalContent, document.body);

위 한 줄만으로 모달은 이제 어떤 부모 구조와도 독립적으로 렌더링됩니다.

---

🛠 트러블슈팅 요약

현상	원인	해결 방법
모달이 상단 메뉴를 가리지 못함	내부 DOM에 렌더링 → 부모의 CSS 영향	React Portal로 DOM 분리
오버레이가 전체 화면을 덮지 않음	부모 요소가 기준이 되는 absolute 구조 때문	fixed + Portal 구조로 교체
어떤 모달은 되고 어떤 모달은 안 되는 현상 발생	DOM 위치에 따라 모달이 렌더링되는 위치가 달랐기 때문	모든 모달을 Portal 기반으로 통일

---

🧾 마무리 정리

React에서 모달, 토스트, 드롭다운 등은 단순한 UI 요소가 아닙니다.

렌더링 위치와 레이어 구조까지 고려한 설계가 필요하며, 이를 가장 안정적으로 해결해주는 것이 바로 React Portal입니다.

저처럼 "모달이 화면 전체를 덮지 못하는 문제"를 겪으셨다면,

모달 구조를 점검하시고, Portal 도입을 고려해보시길 추천드립니다.

---

📌 덤으로: Portal 없이 개발하다가 고생하는 분들에게

“왜 같은 모달인데 하나는 되고 하나는 안 돼?”

이 질문에 답을 줄 수 있는 순간,

React를 더 깊게 이해하게 되신 겁니다. 😉