css-container-queries

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

CSS Container Queries

CSS 容器查询

A guide for implementing container-based responsive design using CSS container queries and Tailwind CSS.

一份关于使用CSS容器查询和Tailwind CSS实现基于容器的响应式设计的指南。

What

是什么

What are Container Queries?

什么是容器查询？

Container queries enable styling elements based on their container's size rather than the viewport size. Unlike media queries that respond to the browser window, container queries make components self-contained and truly reusable.

Key Concept:

css

/* Define a container */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

/* Query the container */
@container card (min-width: 400px) {
  .card-title {
    font-size: 2rem;
  }
}

Tailwind Approach:

html

<!-- Define a container -->
<div class="@container">
  <!-- Query the container -->
  <div class="@lg:grid-cols-2">
    <!-- Content adapts to container, not viewport -->
  </div>
</div>

容器查询允许根据容器的大小而非视口大小来为元素设置样式。与响应浏览器窗口的媒体查询不同，容器查询让组件具备自包含性，真正实现可复用。

核心概念：

css

/* 定义容器 */
.card-wrapper {
  container-type: inline-size;
  container-name: card;
}

/* 查询容器 */
@container card (min-width: 400px) {
  .card-title {
    font-size: 2rem;
  }
}

Tailwind 实现方式：

html

<!-- 定义容器 -->
<div class="@container">
  <!-- 查询容器 -->
  <div class="@lg:grid-cols-2">
    <!-- 内容根据容器而非视口自适应 -->
  </div>
</div>

Container Query vs Media Query

容器查询 vs 媒体查询

Feature	Media Query	Container Query
Responds to	Viewport size	Container size
Reusability	Layout-dependent	Fully portable
Use case	Page layouts	Component styling
Syntax	`@media`	`@container`

特性	媒体查询	容器查询
响应对象	视口大小	容器大小
可复用性	依赖布局	完全可移植
使用场景	页面布局	组件样式
语法	`@media`	`@container`

Why

为什么使用

💡 Why Use Container Queries?

💡 为什么选择容器查询？

1. Component Portability

Components adapt to their context, not the viewport
Same component works in sidebar (narrow) or main area (wide)
No need for different component variants

2. Simpler Component Logic

Components don't need to know about page layout
Follows single responsibility principle
Reduces coupling between components and layouts

3. Better for Design Systems

Components are truly self-contained
Works in any layout context (grid, flex, sidebar)
Easier to maintain and test in isolation

4. Modern Web Architecture

Aligns with component-based frameworks (React, Vue, Svelte)
Better for micro-frontends
More predictable behavior

1. 组件可移植性

组件根据所在上下文自适应，而非视口
同一个组件可在侧边栏（窄）或主内容区（宽）正常工作
无需创建不同的组件变体

2. 更简洁的组件逻辑

组件无需了解页面布局
遵循单一职责原则
减少组件与布局之间的耦合

3. 更适配设计系统

组件真正实现自包含
可在任意布局上下文（网格、弹性布局、侧边栏）中工作
更易于独立维护和测试

4. 符合现代Web架构

与基于组件的框架（React、Vue、Svelte）契合
更适合微前端架构
行为更可预测

When to Use Container Queries vs Media Queries

何时使用容器查询 vs 媒体查询

🤔 Use Container Queries when:

Styling reusable components (cards, widgets, forms)
Component appears in multiple contexts
Component needs to adapt to its parent's size
Building a component library

🤔 Use Media Queries when:

Changing overall page layout
Adjusting navigation structure
Modifying font sizes globally
Viewport-specific features (like mobile-first approach)

🤔 使用容器查询的场景：

为可复用组件（卡片、小组件、表单）设置样式
组件会出现在多个不同上下文
组件需要根据父容器大小自适应
构建组件库

🤔 使用媒体查询的场景：

更改整体页面布局
调整导航结构
全局修改字体大小
视口专属特性（如移动端优先方案）

Requirements

实施要求

What to Do

需完成的事项

Review and refactor responsive components to use container queries where appropriate.

审查并重构响应式组件，在合适的场景下使用容器查询。

Implementation Checklist

实施检查清单

1. CSS Implementation

1. CSS 实现步骤

Step 1: Define the container

css

.component-wrapper {
  container-type: inline-size; /* or 'size' for both dimensions */
  container-name: myComponent; /* optional but recommended */
}

Step 2: Add container queries

css

/* Use the container name */
@container myComponent (min-width: 400px) {
  .component-title {
    font-size: 2rem;
  }
}

/* Or query nearest container */
@container (min-width: 400px) {
  .component-title {
    font-size: 2rem;
  }
}

Step 3: Use modern range syntax (optional)

css

@container (400px <= width <= 800px) {
  .component-content {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
  }
}

步骤1：定义容器

css

.component-wrapper {
  container-type: inline-size; /* 或使用'size'同时适配两个维度 */
  container-name: myComponent; /* 可选但推荐设置 */
}

步骤2：添加容器查询

css

/* 使用容器名称 */
@container myComponent (min-width: 400px) {
  .component-title {
    font-size: 2rem;
  }
}

/* 或查询最近的容器 */
@container (min-width: 400px) {
  .component-title {
    font-size: 2rem;
  }
}

步骤3：使用现代范围语法（可选）

css

@container (400px <= width <= 800px) {
  .component-content {
    display: grid;
    grid-template-columns: repeat(2, 1fr);
  }
}

3. Tailwind CSS Implementation

3. Tailwind CSS 实现步骤

Step 1: Define container with
@container
class

html

<div class="@container">
  <!-- This is now a container context -->
</div>

Step 2: Use container query variants

html

<div class="@container">
  <div class="grid @lg:grid-cols-2 @xl:grid-cols-3">
    <!-- Responds to container size, not viewport -->
  </div>
</div>

Available Tailwind Container Breakpoints:

```
@3xs
```
-
```
@container (width >= 16rem)
```
(256px)
```
@2xs
```
-
```
@container (width >= 18rem)
```
(288px)
```
@xs
```
-
```
@container (width >= 20rem)
```
(320px)
```
@sm
```
-
```
@container (width >= 24rem)
```
(384px)
```
@md
```
-
```
@container (width >= 28rem)
```
(448px)
```
@lg
```
-
```
@container (width >= 32rem)
```
(512px)
```
@xl
```
-
```
@container (width >= 36rem)
```
(576px)
```
@2xl
```
-
```
@container (width >= 42rem)
```
(672px)
```
@3xl
```
-
```
@container (width >= 48rem)
```
(768px)
```
@4xl
```
-
```
@container (width >= 56rem)
```
(896px)
```
@5xl
```
-
```
@container (width >= 64rem)
```
(1024px)
```
@6xl
```
-
```
@container (width >= 72rem)
```
(1152px)
```
@7xl
```
-
```
@container (width >= 80rem)
```
(1280px)

📝 Note: These are Tailwind's default breakpoints. You can customize them in

globals.css

(Tailwind v4) using CSS variables or use arbitrary values like

@min-[500px]:grid

for custom container widths.

Step 3: Named containers (Tailwind)

html

<!-- Define named container -->
<div class="@container/main">
  <!-- Query specific container -->
  <div class="@lg/main:grid-cols-3">
    <!-- Content -->
  </div>
</div>

步骤1：使用
@container
类定义容器

html

<div class="@container">
  <!-- 现在这是一个容器上下文 -->
</div>

步骤2：使用容器查询变体

html

<div class="@container">
  <div class="grid @lg:grid-cols-2 @xl:grid-cols-3">
    <!-- 根据容器大小而非视口大小响应 -->
  </div>
</div>

可用的Tailwind容器断点：

```
@3xs
```
-
```
@container (width >= 16rem)
```
(256px)
```
@2xs
```
-
```
@container (width >= 18rem)
```
(288px)
```
@xs
```
-
```
@container (width >= 20rem)
```
(320px)
```
@sm
```
-
```
@container (width >= 24rem)
```
(384px)
```
@md
```
-
```
@container (width >= 28rem)
```
(448px)
```
@lg
```
-
```
@container (width >= 32rem)
```
(512px)
```
@xl
```
-
```
@container (width >= 36rem)
```
(576px)
```
@2xl
```
-
```
@container (width >= 42rem)
```
(672px)
```
@3xl
```
-
```
@container (width >= 48rem)
```
(768px)
```
@4xl
```
-
```
@container (width >= 56rem)
```
(896px)
```
@5xl
```
-
```
@container (width >= 64rem)
```
(1024px)
```
@6xl
```
-
```
@container (width >= 72rem)
```
(1152px)
```
@7xl
```
-
```
@container (width >= 80rem)
```
(1280px)

📝 注意： 这些是Tailwind的默认断点。你可以在

globals.css

（Tailwind v4）中使用CSS变量自定义，或使用任意值如

@min-[500px]:grid

来设置自定义容器宽度。

步骤3：命名容器（Tailwind）

html

<!-- 定义命名容器 -->
<div class="@container/main">
  <!-- 查询指定容器 -->
  <div class="@lg/main:grid-cols-3">
    <!-- 内容 -->
  </div>
</div>

4. Common Patterns

4. 常见模式

Pattern 1: Card Component

html

<!-- Tailwind -->
<div class="@container">
  <article class="@lg:flex @lg:gap-4">
    <img class="@lg:w-48" src="..." alt="..." />
    <div class="@lg:flex-1">
      <h2 class="text-xl @lg:text-2xl">Title</h2>
      <p class="@lg:text-base">Description</p>
    </div>
  </article>
</div>

Pattern 2: Responsive Grid

html

<!-- Tailwind -->
<div class="@container">
  <div class="grid @sm:grid-cols-2 @lg:grid-cols-3 @2xl:grid-cols-4 gap-4">
    <!-- Items adapt to container width -->
  </div>
</div>

Pattern 3: Mixed Container + Media Queries

html

<!-- Use media queries for layout, container queries for components -->
<main class="max-w-7xl mx-auto md:grid md:grid-cols-3">
  <!-- Sidebar: narrow container -->
  <aside class="md:col-span-1">
    <div class="@container">
      <div class="@lg:hidden">Compact view</div>
    </div>
  </aside>

  <!-- Main: wide container -->
  <div class="md:col-span-2">
    <div class="@container">
      <div class="@2xl:grid-cols-3">Full width view</div>
    </div>
  </div>
</main>

模式1：卡片组件

html

<!-- Tailwind -->
<div class="@container">
  <article class="@lg:flex @lg:gap-4">
    <img class="@lg:w-48" src="..." alt="..." />
    <div class="@lg:flex-1">
      <h2 class="text-xl @lg:text-2xl">标题</h2>
      <p class="@lg:text-base">描述</p>
    </div>
  </article>
</div>

模式2：响应式网格

html

<!-- Tailwind -->
<div class="@container">
  <div class="grid @sm:grid-cols-2 @lg:grid-cols-3 @2xl:grid-cols-4 gap-4">
    <!-- 项目根据容器宽度自适应 -->
  </div>
</div>

模式3：容器查询+媒体查询混合使用

html

<!-- 使用媒体查询处理布局，容器查询处理组件 -->
<main class="max-w-7xl mx-auto md:grid md:grid-cols-3">
  <!-- 侧边栏：窄容器 -->
  <aside class="md:col-span-1">
    <div class="@container">
      <div class="@lg:hidden">紧凑视图</div>
    </div>
  </aside>

  <!-- 主内容区：宽容器 -->
  <div class="md:col-span-2">
    <div class="@container">
      <div class="@2xl:grid-cols-3">全宽视图</div>
    </div>
  </div>
</main>

5. Review Process

5. 审查要点

✅ Focus on:

Recently modified components
Components using media queries for internal layout
Reusable component patterns

⚠️ Watch out for:

Overusing container queries (media queries are still needed for layouts)
Nesting too many containers (can cause confusion)
Not naming containers when multiple are present
Fixed heights (let content flow naturally)

❌ Avoid:

Replacing all media queries with container queries
Container queries for page-level layouts
Complex nesting without clear container names

✅ 重点关注：

近期修改过的组件
使用媒体查询设置内部布局的组件
可复用的组件模式

⚠️ 注意事项：

过度使用容器查询（布局仍需媒体查询）
嵌套过多容器（易造成混淆）
存在多个容器时未命名
固定高度（让内容自然流动）

❌ 避免：

用容器查询替换所有媒体查询
对页面级布局使用容器查询
无明确容器名称的复杂嵌套

6. Testing Checklist

6. 测试检查清单

7. Browser Support

7. 浏览器兼容性

✅ Supported:

Chrome 106+
Edge 106+
Safari 16+
Firefox 110+

💡 Tip: For older browsers, use

@supports

or progressive enhancement:

css

/* Fallback for older browsers */
.component {
  padding: 1rem;
}

/* Enhanced with container queries */
@supports (container-type: inline-size) {
  @container (min-width: 400px) {
    .component {
      padding: 2rem;
    }
  }
}

✅ 支持的浏览器：

Chrome 106+
Edge 106+
Safari 16+
Firefox 110+

💡 提示： 对于旧版浏览器，使用

@supports

或渐进增强方案：

css

/* 旧版浏览器回退方案 */
.component {
  padding: 1rem;
}

/* 使用容器查询增强 */
@supports (container-type: inline-size) {
  @container (min-width: 400px) {
    .component {
      padding: 2rem;
    }
  }
}

Examples

示例

✅ Good: Component-Based Container Query

✅ 良好实践：基于组件的容器查询

html

<!-- Tailwind: Reusable card adapts to any container -->
<div class="@container">
  <article class="p-4 @md:p-6 @lg:flex @lg:gap-6">
    <img class="w-full @lg:w-64 rounded" src="card.jpg" alt="" />
    <div>
      <h2 class="text-lg @md:text-xl @lg:text-2xl font-bold">
        Card Title
      </h2>
      <p class="text-sm @md:text-base @lg:text-lg">
        Card description that adapts to container width.
      </p>
      <button class="mt-4 @md:mt-6">Action</button>
    </div>
  </article>
</div>

Why it's good: Card is self-contained and works in any layout context.

html

<!-- Tailwind：可复用卡片适配任意容器 -->
<div class="@container">
  <article class="p-4 @md:p-6 @lg:flex @lg:gap-6">
    <img class="w-full @lg:w-64 rounded" src="card.jpg" alt="" />
    <div>
      <h2 class="text-lg @md:text-xl @lg:text-2xl font-bold">
        卡片标题
      </h2>
      <p class="text-sm @md:text-base @lg:text-lg">
        根据容器宽度自适应的卡片描述。
      </p>
      <button class="mt-4 @md:mt-6">操作按钮</button>
    </div>
  </article>
</div>

优势： 卡片具备自包含性，可在任意布局上下文工作。

❌ Bad: Using Media Queries for Component Internals

❌ 不良实践：为组件内部使用媒体查询

html

<!-- Tailwind: Component depends on viewport, not container -->
<article class="p-4 md:p-6 lg:flex lg:gap-6">
  <img class="w-full lg:w-64 rounded" src="card.jpg" alt="" />
  <div>
    <h2 class="text-lg md:text-xl lg:text-2xl font-bold">
      Card Title
    </h2>
  </div>
</article>

Why it's bad: Card assumes it's always full width at

md

breakpoint. Breaks when placed in a sidebar.

html

<!-- Tailwind：组件依赖视口而非容器 -->
<article class="p-4 md:p-6 lg:flex lg:gap-6">
  <img class="w-full lg:w-64 rounded" src="card.jpg" alt="" />
  <div>
    <h2 class="text-lg md:text-xl lg:text-2xl font-bold">
      卡片标题
    </h2>
  </div>
</article>

问题： 卡片假设在

md

断点时始终是全宽，放在侧边栏时会失效。

✅ Good: Named Containers for Clarity

✅ 良好实践：命名容器提升清晰度

html

<!-- Tailwind: Multiple containers with clear names -->
<div class="@container/sidebar">
  <nav class="@lg/sidebar:grid-cols-1">
    <!-- Sidebar navigation -->
  </nav>
</div>

<div class="@container/main">
  <div class="@lg/main:grid-cols-3">
    <!-- Main content grid -->
  </div>
</div>

Why it's good: Clear which container each query refers to.

html

<!-- Tailwind：多个容器带有明确名称 -->
<div class="@container/sidebar">
  <nav class="@lg/sidebar:grid-cols-1">
    <!-- 侧边栏导航 -->
  </nav>
</div>

<div class="@container/main">
  <div class="@lg/main:grid-cols-3">
    <!-- 主内容网格 -->
  </div>
</div>

优势： 明确每个查询对应的容器。

Common Mistakes

常见错误

❌ Mistake 1: Using container queries for page layouts

html

<!-- Don't do this -->
<body class="@container">
  <main class="@lg:grid @lg:grid-cols-3">

Fix: Use media queries for page-level layouts.

❌ Mistake 2: Forgetting to define the container

html

<!-- Don't do this -->
<div>
  <div class="@lg:grid-cols-2"><!-- Won't work! --></div>
</div>

Fix: Always add

@container

to the parent.

❌ Mistake 3: Fixed heights with responsive content

css

/* Don't do this */
.container {
  height: 400px; /* Fixed height */
}

@container (min-width: 600px) {
  .content {
    columns: 2; /* Text will overflow! */
  }
}

Fix: Use

min-height

or let content determine height.

❌ Mistake 4: Too many nested containers

html

<!-- Don't do this -->
<div class="@container">
  <div class="@container">
    <div class="@container">
      <div class="@lg:..."><!-- Confusing! --></div>
    </div>
  </div>
</div>

Fix: Use named containers and keep nesting shallow.

❌ 错误1：为页面布局使用容器查询

html

<!-- 不要这样做 -->
<body class="@container">
  <main class="@lg:grid @lg:grid-cols-3">

修复方案： 为页面级布局使用媒体查询。

❌ 错误2：忘记定义容器

html

<!-- 不要这样做 -->
<div>
  <div class="@lg:grid-cols-2"><!-- 不会生效！ --></div>
</div>

修复方案： 始终为父元素添加

@container

。

❌ 错误3：固定高度搭配响应式内容

css

/* 不要这样做 */
.container {
  height: 400px; /* 固定高度 */
}

@container (min-width: 600px) {
  .content {
    columns: 2; /* 文本会溢出！ */
  }
}

修复方案： 使用

min-height

或让内容决定高度。

❌ 错误4：过多嵌套容器

html

<!-- 不要这样做 -->
<div class="@container">
  <div class="@container">
    <div class="@container">
      <div class="@lg:..."><!-- 容易混淆！ --></div>
    </div>
  </div>
</div>

修复方案： 使用命名容器并减少嵌套层级。

Quick Reference

快速参考

Vanilla CSS

原生CSS

css

/* Define container */
.wrapper {
  container-type: inline-size; /* or 'size' */
  container-name: myContainer; /* optional */
}

/* Query container */
@container myContainer (min-width: 400px) {
  /* styles */
}

/* Modern range syntax */
@container (400px <= width <= 800px) {
  /* styles */
}

css

/* 定义容器 */
.wrapper {
  container-type: inline-size; /* 或'size' */
  container-name: myContainer; /* 可选 */
}

/* 查询容器 */
@container myContainer (min-width: 400px) {
  /* 样式 */
}

/* 现代范围语法 */
@container (400px <= width <= 800px) {
  /* 样式 */
}

Tailwind CSS

html

<!-- Define container -->
<div class="@container">
  <!-- Use container variants -->
  <div class="@sm:text-lg @md:grid-cols-2">
</div>

<!-- Named container -->
<div class="@container/name">
  <div class="@lg/name:grid-cols-3">
</div>

html

<!-- 定义容器 -->
<div class="@container">
  <!-- 使用容器变体 -->
  <div class="@sm:text-lg @md:grid-cols-2">
</div>

<!-- 命名容器 -->
<div class="@container/name">
  <div class="@lg/name:grid-cols-3">
</div>

css-container-queries

Original

Translation

CSS Container Queries

CSS 容器查询

What

是什么

What are Container Queries?

什么是容器查询？

Container Query vs Media Query

容器查询 vs 媒体查询

Why

为什么使用

💡 Why Use Container Queries?

💡 为什么选择容器查询？

When to Use Container Queries vs Media Queries

何时使用容器查询 vs 媒体查询

Requirements

实施要求

What to Do

需完成的事项

Implementation Checklist

实施检查清单

1. CSS Implementation

1. CSS 实现步骤

3. Tailwind CSS Implementation

3. Tailwind CSS 实现步骤

4. Common Patterns

4. 常见模式

5. Review Process

5. 审查要点

6. Testing Checklist

6. 测试检查清单

7. Browser Support

7. 浏览器兼容性

Examples

示例

✅ Good: Component-Based Container Query

✅ 良好实践：基于组件的容器查询

❌ Bad: Using Media Queries for Component Internals

❌ 不良实践：为组件内部使用媒体查询

✅ Good: Named Containers for Clarity

✅ 良好实践：命名容器提升清晰度

Common Mistakes

常见错误

Quick Reference

快速参考

Vanilla CSS

原生CSS

Tailwind CSS

Tailwind CSS

Resources

参考资源