[TIL] 2025-09-28 (JavaScript Modal View Unvisible Problem)

새로운 기능을 구현하기 위해 정신없이 코드를 짜다가 만난, 분명 간단해야할 기능이 알 수 없는 이유로 동작하지 않는 순간을 마주했습니다. 바로 제가 원할 때, 원하는 곳에 나타나지 않는 모달(Modal) 문제였습니다. 이 모달은 마치 유령처럼 DOM Queue에 쌓여있다가, 전혀 예상치 못한 순간에 엉뚱한 곳에서 나타났습니다.
 
제가 이 유령같은 모달을 잡기 위해 어떤 과정을 거쳤는지, 그리고 이 경험을 통해 어떤 교훈을 얻었는지 적어보겠습니다.
--------

Problem

Modal이 원하는 곳에서 visible이 되지 않고, DOM에 Queue로 쌓이다가 원하지 않는 곳에서 나오는 문제

--------

Attempts

1. Stacking Context?

가장 먼저 든 생각은 Stacking Context 문제였습니다. css에서 z-index 속성은 요소가 쌓이는 순서를 제어하는데, 이게 가끔 까다롭게 동작할 때가 있습니다. z-index 값이 높으면 다른 요소 위로 올라오지만, 이 규칙은 같은 쌓임 맥락 안에서만 유효합니다. 
 
만약 제가 띄우려는 모달과 페이지의 다른 부분이 서로 다른 쌓임 맥락에 속해 있다면, 모달의 z-index를 9999로 설정해도 다른 요소 뒤에 갇혀 보이지 않을 수 있기 때문에, 모달의 부모 요소들을 검사하며 불필요한 쌓임 맥락을 만드는 속성이 있는지 찾아봤지만, 이것이 원인은 아니었습니다.
 

2. display: flex 속성

다음으로 레이아웃 속성을 살펴보았습니다. 저는 페이지 구조를 잡을 때 Flexbox를 애용합니다. Flexbox는 강력하지만, 때로는 자식 요소의 위치에 예상치 못한 영향을 주기도 합니다. 특히 position: absolute 속성을 가진 모달 같은 요소에는 더욱 그렇습니다. 모달이 Flexbox 컨데이너 안에서 위치를 제대로 잡지 못하고 있는지 확인해 봤지만, 이 또한 문제는 아니었습니다.
 

3. 유령 클래스에 쌓여있어서 보이지 않음.

세 번째 가설은 모달이 DOM에는 존재하지만, 제가 유령 클래스라고 부르기 시작한 무언가에 의해 숨겨져 있다는 것이었습니다. display:none이나 visibility: hidden 같은 스타일을 가진 클래스가 자바스크립트에 의해 제대로 제거되지 않고 남아있을거라 추측했습니다. 모달이 나중에라도 나타나는 현상을, 다른 이벤트가 결국 이 유령 클래스를 제거하기 때문이라고 생각했습니다. 브라우저 개발자 도구를 열어놓고 클릭할 때마다 요소를 관찰했지만, 해당 클래스를 찾을 수는 없었습니다.
 
--------

Solution

4. html 기본 구조의 문제.

이렇게 복잡한 css문제들을 한참 파헤친 후에야, 해결책이 부끄러울 정도로 간단하고 근본적인 곳에 있다는 것을 깨달았습니다. 바로 HTML 구조 자체가 잘못되었던 것입니다. 
기능을 급하게 구현하다보니, 제가 띄우고 싶었던 모달을 또 다른 모달 컴포넌트 안에 중첩해서 배치했던 것 입니다.
잘못된 구조는 다음과 같았습니다. 

해당 모달이 갇힌 모달이었습니다.

 
 
 

이것이 왜 문제였을까?

css 가시성의 기본 규칙은 부모 요소가 보이지 않으면 자식 요소도 보일 수 없다는 것입니다. 제 자바스크립트 코드는 #my-target-modal을 보여주려고 정확히 작동하고 있었지만, 그 부모인 #parent-modal이 display:none 상태였기 때문에 타겟 모달 역시 화면에 나올 수 없었던 것입니다.
 
제가 겪었던 이상한 대기열 현상을 다른 사용자 행동이 결국 #parent-modal을 화면에 표시했을 때 발생했습니다. 그 순간 이미 표시되도록 설정되어 있던 #my-target-modal이 부모와 함께 나타나면서 마치 뒤늦게 출력되는 것처럼 보였던 것입니다.
 
해결책은 모달들이 부모-자식 관계가 아닌 형제 관계가 되도록 HTML구조를 수정하는 방법이었습니다. 사실 이런 문제를 원천적으로 방지하려면 모달은 body 태그 바로 아래에 두어 다른 요소의 스타일에 영향을 받지 않도록 하는 것이 가장 좋습니다.
 

결론 및 교훈

 
이번 경험은 중요한 사실을 다시 한번 일깨워 주었습니다. 디버깅 시에 복잡한 것부터 파고들기 전에, 가장 기본적인 것을 먼저 확인해야한다는 것입니다. css와 js의 복잡함에 빠져 길을 잃기 쉽지만, 때로는 문제의 원인이 페이지의 가장 근간이 되는 HTML 구조에 있을 수 있습니다. 깔끔하고 논리적인 문서 구조는 단순히 의미론적인 접근성 뿐만 아니라, 수만은 스타일링 문제를 예방해 주는 최고의 방어막이 될 수 있다는 것을 꼭 기억하겠습니다.