---
id: wiki-2026-0508-container-queries
title: CSS Container Queries
category: 10_Wiki/Topics
status: verified
canonical_id: self
aliases: [container queries, @container, cqi, cqw, component-centric responsive, design system]
duplicate_of: none
source_trust_level: A
confidence_score: 0.95
verification_status: applied
tags: [css, container-queries, responsive-design, component-driven, design-system, baseline-2025]
raw_sources: []
last_reinforced: 2026-05-10
github_commit: pending
tech_stack:
  language: CSS
  framework: any (vanilla CSS, Tailwind, CSS-in-JS)
---

# CSS Container Queries

## 매 한 줄
> **"매 viewport X — 매 parent container 의 size 의 반응"**. 매 component 의 어디 에 의 placed 의 robust. 매 2025 baseline. 매 design system / modular UI 의 game-changer. 매 page-centric → 매 component-centric paradigm shift.

## 매 핵심

### 매 vs Media Queries
- **Media query**: 매 viewport size.
- **Container query**: 매 parent size.
- 매 component 의 self-decide layout regardless of page placement.

### 매 syntax (basic)
```css
.parent {
  container-type: inline-size;
  container-name: card;  /* 매 optional */
}

@container card (min-width: 600px) {
  .card { display: grid; grid-template-columns: 1fr 1fr; }
}
```

### 매 container-type
- **`inline-size`**: 매 width-based (most common).
- **`size`**: 매 width + height (rarer, more performance).
- **`normal`**: 매 default (no query support).

### 매 unit
- **`cqw`**: 매 1% of container width.
- **`cqh`**: 매 1% of container height.
- **`cqi`**: 매 inline size (LTR/RTL aware).
- **`cqb`**: 매 block size.
- **`cqmin`** / **`cqmax`**: 매 min / max of inline / block.

### 매 use case
1. **Card component**: 매 sidebar (narrow) vs main (wide) 의 다른 layout.
2. **Dashboard tile**: 매 chart → 매 number 의 narrow.
3. **Table → card** (narrow).
4. **Article**: 매 typography 의 cqi 기반 fluid.
5. **Sidebar item**: 매 collapsed vs expanded.

### 매 modern browser support
- 매 Chrome 105+ (2022 Aug).
- 매 Firefox 110+ (2023 Feb).
- 매 Safari 16+ (2022 Sep).
- 매 Baseline widely available 2025.

### 매 design system 의 perfect fit
- 매 component 의 reusable 어디 에서.
- 매 Storybook 의 isolation testing.
- 매 modular UI library.
- 매 truly self-contained component.

### 매 vs media query (when 의 use)
- **Media query**: 매 page layout, 매 dark mode, 매 print.
- **Container query**: 매 component size adaptation.
- 매 둘 다 의 combine.

### 매 fluid typography (cqi)
```css
.title { font-size: clamp(1rem, 4cqi, 2rem); }
```

→ 매 container 의 size 의 따라 fluid scale.

## 💻 패턴

### Card layout (sidebar vs main)
```css
.card-container {
  container-type: inline-size;
}

.card {
  display: flex;
  flex-direction: column;
}

@container (min-width: 400px) {
  .card {
    flex-direction: row;
  }
  .card__image { width: 40%; }
  .card__content { flex: 1; }
}

@container (min-width: 700px) {
  .card {
    grid-template-columns: 1fr 2fr 1fr;
  }
  .card__action { display: block; }
}
```

### Dashboard tile (chart ↔ number)
```css
.tile {
  container-type: inline-size;
}

.chart { display: block; }
.summary-number { display: none; }

@container (max-width: 200px) {
  .chart { display: none; }
  .summary-number { display: block; font-size: 2rem; }
}
```

### Fluid typography
```css
.article {
  container-type: inline-size;
}

.article h1 { font-size: clamp(1.5rem, 5cqi, 3rem); }
.article p { font-size: clamp(0.9rem, 2cqi, 1.1rem); }
```

### Table → Card stack (narrow)
```css
.table-container { container-type: inline-size; }

table { display: table; width: 100%; }

@container (max-width: 600px) {
  table, thead, tbody, tr, td { display: block; }
  thead { display: none; }
  tr {
    border: 1px solid #ddd;
    margin-bottom: 1rem;
    padding: 1rem;
  }
  td::before {
    content: attr(data-label) ': ';
    font-weight: bold;
  }
}
```

### Named container
```css
.article-context {
  container-type: inline-size;
  container-name: article;
}

.aside-context {
  container-type: inline-size;
  container-name: aside;
}

@container article (min-width: 600px) {
  .my-component { /* ... */ }
}

@container aside (min-width: 200px) {
  .my-component { /* ... */ }
}
```

### React + container queries
```tsx
function Card({ data }) {
  return (
    <div className="card-container">
      <article className="card">
        <img src={data.image} />
        <div className="card__content">
          <h3>{data.title}</h3>
          <p>{data.description}</p>
        </div>
      </article>
    </div>
  );
}

// 매 CSS:
// .card-container { container-type: inline-size; }
// @container (min-width: 400px) { .card { display: grid; } }
```

### Tailwind v4 (container queries plugin or built-in)
```jsx
<div className="@container">
  <div className="@md:flex @lg:grid @lg:grid-cols-2">
    {/* ... */}
  </div>
</div>
```

### Storybook isolation test
```js
// 매 Storybook 의 다른 sizes 의 test
export const Card = {
  render: () => <Card data={mockData} />,
  decorators: [
    (Story, { args }) => (
      <div style={{ width: args.containerWidth }}>
        <Story />
      </div>
    ),
  ],
  argTypes: {
    containerWidth: {
      control: { type: 'select' },
      options: ['200px', '400px', '600px', '900px'],
    },
  },
};
```

### Browser support fallback
```css
/* 매 default (no support or narrow) */
.card { display: block; }

/* 매 supports query */
@supports (container-type: inline-size) {
  .card-container { container-type: inline-size; }
  
  @container (min-width: 400px) {
    .card { display: flex; }
  }
}
```

### Style queries (newer)
```css
/* 매 Chrome 111+: 매 style 의 query 도 가능 */
@container style(--theme: dark) {
  .text { color: white; }
}
```

## 🤔 결정 기준
| 상황 | Approach |
|---|---|
| Component reuse in different placement | Container query |
| Page-level layout | Media query |
| Dark mode | Media query (prefers-color-scheme) |
| Fluid typography | clamp() + cqi |
| Sidebar vs main differential | Container query |
| Dashboard tile | Container query |
| Print | Media query (print) |

**기본값**: 매 component-level = Container query. 매 page-level = Media query. 매 둘 다 의 combine OK.

## 🔗 Graph
- 부모: [[Responsive-Design]]
- 변형: [[Media-Queries]] · [[Fluid-Typography]]
- 응용: [[Design-System]] · [[Storybook]] · [[Tailwind]] · [[CSS Animations]]
- Adjacent: [[Baseline-Project]] · [[Bounded-Contexts]] · [[Architecture-Styles]]

## 🤖 LLM 활용
**언제**: 매 modern responsive design. 매 design system 구축. 매 component library.
**언제 X**: 매 viewport-only concern (use media query). 매 < 2022 browser support.

## ❌ 안티패턴
- **Container 미지정 (container-type X)**: 매 query 의 동작 X.
- **Media query 만 의 component**: 매 reuse 시 의 fail.
- **container-type: size (large doc)**: 매 performance.
- **No container-name (multiple container)**: 매 confusion.
- **Fallback 의 X**: 매 older browser 의 break.

## 🧪 검증 / 중복
- Verified (web.dev container queries, MDN, Baseline 2025).
- 신뢰도 A.
- Related: [[CSS Animations]] · [[Baseline-Project]] · [[Case-Study-Allbirds-PWA-Redesign]] · [[Component-Driven-Design]].

## 🕓 Changelog
| 날짜 | 변경 |
|---|---|
| 2026-05-08 | Phase 1 |
| 2026-05-10 | Manual cleanup — syntax + cq* unit + 매 card / dashboard / table / Tailwind code |