컨테이너 쿼리는 컴포넌트가 브라우저 뷰포트 대신 부모 컨테이너의 크기에 반응하게 합니다. 오랫동안 CSS 위시리스트 항목이었다가 이제 97% 브라우저 지원에 도달하여 프로덕션 사용 준비가 됐습니다. 이 가이드는 컨테이너 쿼리가 빛나는 곳과 미디어 쿼리에서 마이그레이션하는 방법을 보여줍니다.
컴포넌트에 미디어 쿼리의 문제
미디어 쿼리는 뷰포트에 작동합니다. 넓은 너비에서 2열, 좁은 너비에서 1열이어야 하는 카드 컴포넌트는 미디어 쿼리로 자신의 너비를 알 수 없습니다 — 뷰포트 너비만 압니다.
이것이 "사이드바 문제"를 만듭니다: 3열 그리드에서 완벽해 보이는 카드(뷰포트 800px)가 사이드바에 같은 컴포넌트를 배치하면 깨집니다(뷰포트 여전히 800px, 하지만 카드는 250px).
컨테이너 쿼리 문법
먼저 부모에 격리 컨텍스트를 설정하세요:
.card-container { container-type: inline-size; }
그다음 자식에서 컨테이너 너비를 쿼리하세요:
@container (min-width: 400px) { .card { display: grid; grid-template-columns: 1fr 1fr; } }
@container 규칙은 container-type이 있는 가장 가까운 조상이 최소 400px일 때 발동합니다 — 뷰포트 크기에 관계없이.
container-type 값
| 값 | 추적 대상 |
|---|---|
| inline-size | 너비만 (가장 일반적) |
| size | 너비와 높이 모두 |
| normal | 격리 없음 (기본값) |
컨테이너 쿼리 vs 미디어 쿼리 사용 시기
- 컨테이너 쿼리 사용: 컴포넌트 수준 반응형 — 레이아웃 어디에나 배치 가능한 카드, 사이드바, 위젯.
- 미디어 쿼리 사용: 페이지 수준 반응형 — 전체 뷰포트 크기에 의존하는 내비게이션 변경, 그리드 중단점.
- 컨테이너 쿼리는 미디어 쿼리의 대체가 아닙니다 — 보완적입니다. 대부분의 반응형 디자인은 두 가지 모두 활용합니다.
브라우저 지원
컨테이너 쿼리는 Chrome 105+, Firefox 110+, Safari 16+에서 지원됩니다 — 2026년 97%+ 브라우저를 커버합니다. JavaScript 폴리필 없이 프로덕션에서 사용할 수 있습니다.