7onicDESIGN SYSTEM

z-Index

UI 요소의 쌓임 순서를 일관된 규칙으로 관리합니다. Dropdown, Modal, Tooltip 등 레이어가 충돌하지 않는 설계입니다.

z-Index Scale

기본 숫자 값과 시맨틱 토큰, 두 가지 카테고리로 구성됩니다.

기본값 (0–50)

0
z-0
10
z-10
20
z-20
30
z-30
40
z-40
50
z-50

시맨틱 값

z-sticky100

스티키 헤더, 고정 요소

z-dropdown1000

드롭다운 메뉴, 셀렉트

z-overlay1100

오버레이, 배경 마스크

z-modal2000

모달 다이얼로그

z-popover2100

팝오버, 호버 카드

z-tooltip2200

툴팁

z-toast3000

토스트 알림 (최상위)

Interactive Demo

각 요소를 클릭해 z-index 계층을 확인해보세요.

Base Content
z-index: 0
Dropdown
z-1000
Modal Dialog
z-index: 2000

드롭다운보다 앞에 표시됩니다

Tooltip
z-2200

Recommended Values

각 UI 컴포넌트에 적합한 z-index 토큰

Header (sticky)

z-sticky
100

Dropdown Menu

z-dropdown
1000

Select Options

z-dropdown
1000

Backdrop/Overlay

z-overlay
1100

Modal/Dialog

z-modal
2000

Popover

z-popover
2100

Tooltip

z-tooltip
2200

Toast/Notification

z-toast
3000

Layer Hierarchy

z-index 값이 높을수록 앞에 표시됩니다.

Base일반 콘텐츠
z-0-50
Sticky고정 헤더
z-100
Dropdown메뉴
z-1000
Overlay배경 마스크
z-1100
Modal다이얼로그
z-2000
Popover팝업 카드
z-2100
Tooltip호버 힌트
z-2200
Toast알림 메시지
z-3000
위로 갈수록 z-index 값이 높고 앞에 표시

Common Issues

z-index 관련 자주 발생하는 문제와 해결 방법

모달이 드롭다운 뒤에 숨는 문제

→ 드롭다운이 새로운 스태킹 컨텍스트를 생성하고 있음

✓ Portal을 사용해 모달을 body 바로 아래에 렌더링

z-index: 9999 를 줘도 요소가 앞에 오지 않는 문제

→ 부모 요소의 스태킹 컨텍스트에 제한되어 있음

✓ 부모 요소의 z-index를 확인하거나 isolation: isolate 사용

position: fixed 요소가 모달 뒤에 있는 문제

→ fixed여도 적절한 z-index가 필요

✓ z-modal보다 높은 z-index(z-toast 등) 사용

Stacking Context

스태킹 컨텍스트란?

z-index는 같은 스태킹 컨텍스트 내에서만 비교됩니다. 새로운 스태킹 컨텍스트는 다음과 같은 경우에 생성됩니다:

  • •position: absolute/relative/fixed와 z-index가 설정된 요소
  • •opacity가 1 미만인 요소
  • •transform, filter, perspective가 설정된 요소
  • •isolation: isolate가 설정된 요소

Best Practices

✓

권장

  • ✓시맨틱 토큰(z-modal 등) 활용
  • ✓Portal을 사용해 모달을 body 바로 아래에 렌더링
  • ✓isolation: isolate로 컨텍스트를 명시적으로 제어
  • ✓z-index 계층 구조를 사전에 계획
✕

지양

  • ✗z-index: 9999 같은 임의의 큰 값 사용
  • ✗문제가 생길 때마다 z-index를 올리는 것
  • ✗스태킹 컨텍스트를 고려하지 않은 구현
  • ✗하드코딩된 z-index 값 남용