CSS Container Queries 완벽 가이드 — 컴포넌트 단위 반응형 디자인의 새 표준

Container Queries와 미디어 쿼리의 근본적 차이

기존 미디어 쿼리는 브라우저 뷰포트의 너비와 높이를 기준으로 스타일을 조건부 적용한다. 이 방식은 컴포넌트가 전체 화면 너비를 차지할 때는 잘 동작하지만, 같은 컴포넌트가 사이드바나 모달 내부의 좁은 공간에 배치될 때는 뷰포트 크기가 동일해도 레이아웃이 의도와 다르게 표시된다. 컨테이너 쿼리는 부모 컨테이너의 크기를 기준으로 스타일을 적용하여 이 문제를 해결한다. 컴포넌트가 어떤 레이아웃 컨텍스트에 배치되든 자신이 차지할 수 있는 공간에 맞게 자동으로 최적화된다.

/* 컨테이너 정의 */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

/* 컨테이너 너비 기준 스타일 */
@container card (min-width: 480px) {
  .card {
    display: flex;
    flex-direction: row;
    gap: 1.5rem;
  }
  .card__image { width: 200px; flex-shrink: 0; }
}

/* 좁은 컨테이너에서는 수직 레이아웃 (기본값) */
.card { display: flex; flex-direction: column; }

Container Queries container-type과 container-name 사용법

container-type: inline-size를 부모 요소에 선언하면 해당 요소가 인라인 방향(너비) 컨테이너 컨텍스트가 된다. container-type: size를 사용하면 너비와 높이 모두를 기준으로 쿼리할 수 있지만, 성능 비용이 더 높다. container-name으로 컨테이너에 이름을 부여하면 @container card (min-width: 400px) 형태로 특정 컨테이너를 명시적으로 참조할 수 있어, 중첩된 컨테이너 구조에서 원하는 컨테이너의 크기에 반응하도록 제어할 수 있다.

Container Queries로 재사용 가능한 카드 컴포넌트 설계

카드 컴포넌트에 컨테이너 쿼리를 적용하면 그리드, 사이드바, 모달, 드로어 등 어떤 컨텍스트에 배치되어도 자동으로 레이아웃이 최적화된다. 480px 이상 컨테이너에서는 이미지와 텍스트를 수평으로 배치하고, 이하에서는 수직으로 전환하는 반응형 카드를 JavaScript 없이 CSS만으로 구현할 수 있다. 이 패턴은 디자인 시스템의 컴포넌트를 다양한 레이아웃 컨텍스트에서 일관되게 사용할 수 있게 하여 재사용성을 크게 높인다.

Container Queries 스타일 쿼리 활용

스타일 쿼리를 사용하면 부모 요소의 CSS 사용자 정의 변수 값을 기준으로 자식 스타일을 조건부 적용할 수 있다. @container style(--theme: dark)처럼 커스텀 속성 값에 반응하는 컴포넌트를 만들면 부모에서 테마 변수만 변경해도 자식 컴포넌트의 모든 스타일이 자동으로 전환된다. 다크 모드, 브랜드 테마 전환, 강조 표시 상태 등을 CSS 변수 하나로 컨트롤하는 설계에 유용하다.

Container Queries와 Tailwind CSS 통합

Tailwind CSS v4에서는 컨테이너 쿼리가 기본 지원된다. @container 클래스로 컨테이너를 지정하고, @md:flex-row처럼 반응형 접두사 앞에 @를 붙여 컨테이너 기반 조건을 표현한다. v3에서는 @tailwindcss/container-queries 플러그인을 설치하여 동일한 기능을 사용할 수 있다. 임의의 컨테이너 크기는 @[480px]:flex-row 형태로 지정한다.

Container Queries 브라우저 지원 현황과 폴백

2025년 기준 주요 브라우저의 최신 두 버전에서 컨테이너 쿼리가 안정적으로 지원되어 프로덕션 사용이 안전하다. 지원하지 않는 구형 브라우저를 위한 폴백이 필요하다면, 기본 스타일로 적절히 표시되도록 CSS를 설계하거나 cq-polyfill 폴리필을 사용할 수 있다. @supports (container-type: inline-size) 조건문으로 지원 여부에 따라 분기하는 방법도 있다.