웹 애플리케이션 개발 중 Bootstrap 모달(Modal) 창 내부의 입력 필드에 jQuery UI Autocomplete 기능을 구현할 때, 자동 완성 제안 목록이 모달 레이어 뒤에 나타나 사용자에게 보이지 않는 문제가 자주 발생합니다. 이는 각 요소의 CSS z-index 속성 우선순위 차이로 인해 발생하는 전형적인 레이어 겹침 문제입니다.
1. 원인 분석
Bootstrap 모달은 기본적으로 매우 높은 z-index(보통 1050 이상)를 할당받아 화면의 최상단에 위치합니다. 반면, jQuery UI Autocomplete가 동적으로 생성하는 목록(.ui-autocomplete)은 기본 z-index가 낮게 설정되어 있거나 명시되지 않아 모달 배경 또는 본체에 가려지게 됩니다.
2. CSS를 이용한 레이어 우선순위 조정
가장 효율적인 해결책은 CSS를 통해 .ui-autocomplete 클래스의 z-index 값을 Bootstrap 모달보다 높게 강제 설정하는 것입니다. 아래의 코드를 스타일시트에 추가합니다.
/* Autocomplete 목록이 모달 위로 올라오도록 설정 */
.ui-autocomplete {
z-index: 2000 !important; /* Bootstrap 모달의 z-index보다 높게 설정 */
max-height: 300px;
overflow-y: auto;
overflow-x: hidden;
}
이때 중요한 점은 z-index 값뿐만 아니라 CSS 파일이 로드되는 순서입니다. jQuery UI의 기본 스타일시트가 로드된 이후에 커스텀 스타일이 적용되어야 스타일 덮어쓰기가 정상적으로 작동합니다.
3. 리소스 로드 순서 관리
여러 CSS 라이브러리를 사용할 경우, 커스텀 수정 사항이 담긴 파일을 가장 마지막에 배치하여 우선순위를 확보해야 합니다. ASP.NET MVC 환경의 BundleConfig나 일반 HTML 구조에서 다음과 같이 순서를 구성하는 것이 권장됩니다.
<!-- 1. 라이브러리 기본 스타일 -->
<link href="/css/bootstrap.min.css" rel="stylesheet" />
<link href="/css/jquery-ui.min.css" rel="stylesheet" />
<!-- 2. 플러그인 확장 스타일 -->
<link href="/css/jquery-ui-datepicker.css" rel="stylesheet" />
<!-- 3. 최종 수정을 위한 커스텀 CSS (가장 마지막에 위치) -->
<link href="/css/site-custom-overrides.css" rel="stylesheet" />
4. jQuery UI 'appendTo' 옵션 활용
CSS 수정 외에도 jQuery UI Autocomplete의 appendTo 옵션을 사용하여 제안 목록이 생성되는 DOM 위치를 변경할 수 있습니다. 모달 컨테이너 내부에 목록을 생성하면 모달의 컨텍스트를 따르게 되어 레이어 문제가 완화될 수 있습니다.
$("#search-input").autocomplete({
source: availableTags,
appendTo: "#myModal" // 제안 목록이 생성될 부모 요소 지정
});
다만, 대부분의 상황에서는 전역 CSS 파일에 높은 z-index 값을 설정하는 방식이 가장 직관적이고 유지보수가 용이합니다.