Tailwind CSS v4 Container Queries 完整教學：打造真正元件級響應式設計

你有沒有遇過這種情況：一個 Card 元件在全寬的時候排版完美，但塞進側邊欄之後就整個爆掉？用 @media 的 viewport breakpoint 根本沒辦法解決這個問題，因為螢幕寬度沒變，變的是容器的寬度。

這就是 Container Queries（容器查詢）解決的痛點。而在 Tailwind CSS v4 裡，Container Queries 已經是內建功能，不需要任何 plugin。今天我來手把手教你怎麼用 Tailwind v4 的容器查詢，打造真正能在任何容器尺寸下自動適配的元件。

Container Queries vs Media Queries：差在哪？

先搞清楚核心差異：

• Media Queries：根據瀏覽器視窗（viewport）的寬度來切換樣式
• Container Queries：根據父容器的寬度來切換樣式

舉個例子：同一個 ProductCard 元件，放在三欄佈局的時候容器只有 300px 寬，放在 hero section 的時候有 800px 寬。用 Media Query，兩個位置看到的是一樣的佈局（因為 viewport 沒變）。用 Container Query，元件會根據自己所在的容器寬度自動調整。

這才是真正的元件級響應式設計——元件不需要知道自己被放在哪裡，它只需要知道自己有多少空間。

Tailwind CSS v4 的 Container Query 語法

在 Tailwind v4 裡，使用容器查詢分兩步：

Step 1：把父元素標記為容器

<div class="@container">
  <!-- 子元素可以用容器查詢 -->
</div>

@container 這個 utility class 會把元素設定為 container-type: inline-size，這是讓 Container Query 生效的前提。

Step 2：在子元素上使用容器斷點

<div class="@container">
  <div class="flex flex-col @md:flex-row @lg:grid @lg:grid-cols-3">
    <!-- 容器寬度 < 448px：垂直排列 -->
    <!-- 容器寬度 >= 448px：水平排列 -->
    <!-- 容器寬度 >= 512px：三欄 grid -->
  </div>
</div>

Tailwind v4 預設的容器斷點跟 viewport 斷點類似，但加了 @ 前綴：

• @xs：320px
• @sm：384px
• @md：448px
• @lg：512px
• @xl：576px
• @2xl：672px

實戰範例：自適應 ProductCard

來做一個在任何容器尺寸下都能完美顯示的商品卡片：

<div class="@container">
  <article class="flex flex-col @sm:flex-row gap-4 p-4 rounded-lg border">
    <!-- 圖片 -->
    <img 
      src="/product.jpg" 
      class="w-full @sm:w-40 @md:w-48 aspect-square object-cover rounded-md"
      alt="Product"
    />
    <!-- 內容 -->
    <div class="flex-1">
      <h3 class="text-base @md:text-lg font-semibold">商品名稱</h3>
      <p class="text-sm text-gray-600 mt-1 line-clamp-2 @lg:line-clamp-none">
        這是商品描述，在小容器裡會截斷，大容器裡會完整顯示。
      </p>
      <div class="flex items-center gap-2 mt-3">
        <span class="text-lg @md:text-xl font-bold text-red-600">$299</span>
        <button class="ml-auto px-3 py-1.5 @md:px-4 @md:py-2 bg-blue-600 text-white rounded-md text-sm">
          加入購物車
        </button>
      </div>
    </div>
  </article>
</div>

這個 ProductCard 放在三欄 grid 裡會垂直排列（因為每欄只有約 350px），放在兩欄或全寬的位置就會自動變成水平排列。完全不需要寫任何 @media。

具名容器：更精確的控制

當你有巢狀容器的時候，可以用具名容器來指定查詢哪個容器：

<div class="@container/sidebar">
  <div class="@container/card">
    <!-- 查詢外層 sidebar 容器 -->
    <p class="@md/sidebar:text-lg">...</p>
    <!-- 查詢內層 card 容器 -->
    <p class="@sm/card:font-bold">...</p>
  </div>
</div>

自訂容器斷點

Tailwind v4 的 CSS-first 配置讓自訂斷點變得很直覺：

/* 在你的 CSS 檔案裡 */
@theme {
  --container-3xs: 160px;
  --container-2xs: 240px;
  --container-xs: 320px;
  /* 覆蓋或新增斷點 */
}

這比之前 v3 要在 tailwind.config.js 裡設定方便多了。如果你對 Tailwind 的 utility 組合模式有興趣，可以看看Tailwind @apply 自訂元件樣式那篇。

跟 CSS Grid 搭配：真正的彈性佈局

Container Queries 搭配 CSS Grid 可以做出超彈性的 dashboard 佈局：

<div class="@container">
  <div class="grid grid-cols-1 @md:grid-cols-2 @xl:grid-cols-4 gap-4">
    <div class="p-4 bg-white rounded-lg shadow">
      <p class="text-2xl @lg:text-3xl font-bold">1,234</p>
      <p class="text-sm text-gray-500">Total Users</p>
    </div>
    <!-- 更多 stat cards -->
  </div>
</div>

不管這個 dashboard widget 被放在全寬頁面還是側邊面板，stat cards 都會自動調整成最適合的欄數。

瀏覽器支援與注意事項

Container Queries 在 2026 年已經被所有主流瀏覽器支援（Chrome 105+, Firefox 110+, Safari 16+），所以可以放心用在 production。

幾個注意事項：

• @container 設定的是 container-type: inline-size，只能查詢寬度，不能查詢高度
• 容器元素本身會建立新的 containing block，可能影響 position: absolute 的子元素
• 不要把 @container 設在太多層級上，每個容器查詢都有微小的效能成本

小結

Container Queries 是 CSS 近年來最重要的新功能之一，而 Tailwind CSS v4 讓它的使用體驗變得極為順暢。從今天開始，當你在寫響應式設計的時候，先想一下：這個排版變化是因為「螢幕變窄」還是「容器變窄」？如果是後者，@container + @md: 就是你的最佳選擇。

真正的元件化設計，就是讓元件自己決定自己長什麼樣子。Container Queries 讓這件事終於變得可能。