CSS Container Queries는 2023년 모든 주요 브라우저에서 지원이 완료된 이후, 2025-2026년 반응형 웹 디자인의 새로운 표준으로 자리잡았다. 기존 미디어 쿼리가 뷰포트 크기에 반응했다면, Container Queries는 부모 컨테이너의 크기에 반응하여 진정한 컴포넌트 기�� 반응형 디자인을 가능하게 한다.

미디어 쿼리의 한계

미디어 쿼리는 뷰포트 크기만 참조하므로, 동일한 카드 컴포넌트가 사이드바와 메인 영역에서 다르게 보여야 할 때 대응이 어렵다.

/* 미디어 쿼리 - 뷰포트 기준이라 컴포��트 재사용 시 문제 */
@media (max-width: 768px) {
    .card { flex-direction: column; }
}
/* 데스크톱에서도 좁은 사이드바에 카드가 들어가면?
   뷰포트는 넓지만 카드 영역은 좁음 - 대응 불가 */

Container Queries 기본 사용법

/* 1. 컨테이너 정의 */
.card-wrapper {
    container-type: inline-size;  /* 가로 크기 기준 */
    container-name: card-container;
}

/* 2. 컨테이너 크기에 반응하는 스타일 */
.card {
    display: grid;
    grid-template-columns: 200px 1fr;
    gap: 1rem;
    padding: 1rem;
}

/* 컨테이너가 500px 미만일 때 세로 레이��웃 */
@container card-container (max-width: 500px) {
    .card {
        grid-template-columns: 1fr;
    }
    .card__image {
        aspect-ratio: 16 / 9;
    }
}

/* 컨테이너가 300px 미만일 때 더 컴팩트하게 */
@container card-container (max-width: 300px) {
    .card {
        padding: 0.5rem;
    }
    .card__title {
        font-size: 0.875rem;
    }
    .card__description {
        display: none;  /* 설명 숨김 */
    }
}

container-type 옵션

/* inline-size: 가로 크기만 추적 (가장 많이 사용) */
.sidebar {
    container-type: inline-size;
}

/* size: 가로 + 세로 크기 모두 추적 */
.resizable-panel {
    container-type: size;
}

/* normal: 크기 쿼리 불가, 스타일 쿼리만 가능 */
.theme-wrapper {
    container-type: normal;
}

/* 축약형: container 속성으로 type과 name을 동시에 */
.widget-area {
    container: widget / inline-size;
}

실전 예제: 반응형 카드 컴포넌트

<!-- HTML 구조 -->
<div class="grid">
    <!-- 메인 영역: 넓은 공간 -->
    <main class="main-content">
        <div class="card-container">
            <article class="card">
                <img class="card__image" src="photo.jpg" alt="제품 사진">
                <div class="card__body">
                    <h3 class="card__title">제품명</h3>
                    <p class="card__desc">상세 설명...</p>
                    <span class="card__price">89,000원</span>
                </div>
            </article>
        </div>
    </main>
    
    <!-- 사이드바: 좁은 공간 - 동일 컴포넌트가 자동 적응 -->
    <aside class="sidebar">
        <div class="card-container">
            <article class="card">
                <img class="card__image" src="photo.jpg" alt="제품 사진">
                <div class="card__body">
                    <h3 class="card__title">제품명</h3>
                    <p class="card__desc">상세 설명...</p>
                    <span class="card__price">89,000원</span>
                </div>
            </article>
        </div>
    </aside>
</div>

/* CSS */
.grid {
    display: grid;
    grid-template-columns: 1fr 300px;
    gap: 2rem;
}

.card-container {
    container: card / inline-size;
}

.card {
    display: flex;
    border: 1px solid #e0e0e0;
    border-radius: 12px;
    overflow: hidden;
    background: white;
}

.card__image {
    width: 200px;
    object-fit: cover;
}

.card__body {
    padding: 1.5rem;
    display: flex;
    flex-direction: column;
    gap: 0.5rem;
}

.card__title {
    font-size: 1.25rem;
    font-weight: 700;
}

.card__price {
    font-size: 1.125rem;
    font-weight: 600;
    color: #2563eb;
    margin-top: auto;
}

/* 컨테이너 500px 미만: 세로 레이아웃 */
@container card (max-width: 500px) {
    .card {
        flex-direction: column;
    }
    .card__image {
        width: 100%;
        height: 200px;
    }
}

/* 컨테이너 300px 미만: 미니 카드 */
@container card (max-width: 300px) {
    .card__image {
        height: 120px;
    }
    .card__body {
        padding: 0.75rem;
    }
    .card__title {
        font-size: 0.9rem;
    }
    .card__desc {
        display: none;
    }
}

Container Query Units

컨테이너 크기에 비례하는 새로운 단위를 사용할 수 있다.

/* Container Query Units */
.card__title {
    /* cqw: 컨테이너 너비의 1% */
    font-size: clamp(0.875rem, 4cqw, 1.5rem);
}

.card__image {
    /* cqh: 컨테이너 높이의 1% */
    /* cqi: 컨테이너 inline ���기의 1% */
    /* cqb: 컨테이너 block 크기의 1% */
    /* cqmin: cqi와 cqb 중 작은 값 */
    /* cqmax: cqi와 cqb 중 큰 값 */
    height: 40cqi;
}

/* 실용적 활용: 컨테이너 크기에 비례하는 여백 */
.card__body {
    padding: clamp(0.5rem, 3cqi, 2rem);
    gap: clamp(0.25rem, 1.5cqi, 1rem);
}

Style Queries (스타일 쿼리)

컨테이너의 CSS 커스텀 속성(변수) 값에 따라 스타일을 변경할 수 있다.

/* 컨테이너에 테마 변수 설정 */
.theme-light {
    --theme: light;
    container-type: normal;
}

.theme-dark {
    --theme: dark;
    container-type: normal;
}

/* 스타일 쿼리로 테마에 반응 */
@container style(--theme: dark) {
    .card {
        background: #1e1e1e;
        color: #ffffff;
        border-color: #333;
    }
    .card__price {
        color: #60a5fa;
    }
}

@container style(--theme: light) {
    .card {
        background: #ffffff;
        color: #1a1a1a;
        border-color: #e0e0e0;
    }
}

미디어 쿼리와 조합

/* 미디어 쿼리: 전체 레이아웃 담당 */
@media (max-width: 768px) {
    .grid {
        grid-template-columns: 1fr;  /* 사이드바 아래로 */
    }
}

/* Container Query: 컴포넌트 내부 레이아웃 담당 */
@container card (max-width: 500px) {
    .card {
        flex-direction: column;
    }
}

/* 이 조합이 최적의 반응형 전략 */
/* 미디어 쿼리 = 매크로 레이아웃 (페이지 구조) */
/* Container Query = 마이크로 레이아웃 (컴포넌트 내부) */

접근성 고려사항

/* prefers-reduced-motion과 함께 사용 */
@container card (max-width: 500px) {
    .card {
        flex-direction: column;
        transition: all 0.3s ease;
    }
}

@media (prefers-reduced-motion: reduce) {
    .card {
        transition: none;
    }
}

/* prefers-color-scheme + Container Query */
@media (prefers-color-scheme: dark) {
    .card-container {
        --theme: dark;
    }
}

@container style(--theme: dark) {
    .card {
        background: #1e1e1e;
        color: #f0f0f0;
    }
}

Container Queries는 컴포넌트 기반 프론트엔드 개발에서 핵심 도구가 되었다. React, Vue, Svelte 등의 컴포넌트와 결합하면, 진정으로 재사용 가능하고 자체 반응형인 UI 컴포넌트를 만들 수 있다. 미디어 쿼리로 전체 레이아웃을, Container Queries로 컴포넌트 내부를 관리하는 전략을 권장한다.