Chapter 20: Responsive Tables

Container Queries for Tables

Engineering component-driven responsive tables using CSS Container Queries (`container-type: inline-size` and `@container`), eliminating viewport coupling for sidebar and widget embeds.

LEARNING OBJECTIVES ⌵

Understand why global Viewport Media Queries (@media) fail when responsive table components are embedded in narrow containers or sidebars.
Implement modern CSS Container Queries using container-type: inline-size and container-name.
Construct modular, context-aware tabular components that reflow between multi-column matrices and card stacks based on parent width.
Apply Container Query Length Units (cqi, cqw) for fluid typography and dynamic cell padding.

🎬 INTERACTIVE VISUAL PIPELINE Core Architecture Simulation

🌐

1. Input

Directives & Tags

⚙️

2. Parse

Tokenizer & AST

🌳

3. Layout

Box Model & Flow

🎨

4. Render

GPU Paint & Composite

PHASE 1: INPUT & DIRECTIVES

Browser receives declarative markup stream, parsing tag tokens and initializing component state.

📖 The Mental Model & Story (Intuitive Foundation)

Imagine a modern enterprise dashboard on a 32-inch 4K widescreen monitor ($3840\text{px}$ wide). The dashboard features a large main canvas on the left ($2800\text{px}$) and a narrow collapsible analytics sidebar on the right ($320\text{px}$).

4K Monitor Viewport (3840px Wide):
+-------------------------------------------------------------+-----------------------+
| Main Workspace Canvas (2800px Wide)                         | Sidebar (320px Wide)  |
|                                                             |                       |
| [ Recent Invoices Table Component ]                         | [ Recent Invoices     |
| +---------------------------------------------------------+ |   Table Component ]   |
| | ID    | Customer   | Date       | Amount   | Status     | |                       |
| | #101  | Acme Corp  | 2026-08-20 | $1,200   | Paid       | | ??? WHAT HAPPENS    |
| +---------------------------------------------------------+ |     UNDER @media ???  |
+-------------------------------------------------------------+-----------------------+

If you design the "Recent Invoices Table" using traditional Viewport Media Queries (@media (max-width: 768px)), the browser checks the global screen width ($3840\text{px}$). Because $3840\text{px} > 768\text{px}$, the table inside the $320\text{px}$ sidebar is forced to render in full desktop mode (5 columns), causing catastrophic horizontal blowout inside the sidebar!

CSS Container Queries solve this architectural flaw. Instead of asking "How wide is the user's monitor?", the table component asks "How wide is the container I am currently sitting in?". If embedded in the main canvas ($2800\text{px}$), it renders as a wide data matrix; if embedded in the sidebar ($320\text{px}$), it automatically reflows into vertical cards—even on a 4K screen.

Technical Deep Dive & Specifications

Establishing a Containment Context

To enable container queries, an ancestor element must be declared as a query container using the container-type property (CSS Containment Module Level 3):

.table-widget-container {
  /* Declares this element as a container query context on its inline (horizontal) axis */
  container-type: inline-size;
  /* Optional: Names the container to avoid ambiguity with nested containers */
  container-name: table-widget;
}

+-------------------------------------------------------------------------------+
| Container Property | Value        | Technical Purpose                         |
+-------------------------------------------------------------------------------+
| `container-type`   | `inline-size`| Queries the container's horizontal width. |
| `container-type`   | `size`       | Queries both horizontal width AND height. |
| `container-type`   | `normal`     | Default: Element is not a query container.|
| `container-name`   | `<identifier>`| Gives the container an explicit scope.   |
+-------------------------------------------------------------------------------+

The `@container` Rule Syntax

Once a container context is established, child elements apply conditional styles based on the container's inline size:

/* Unnamed container query */
@container (max-width: 550px) {
  .responsive-table,
  .responsive-table tbody,
  .responsive-table tr,
  .responsive-table td {
    display: block;
  }
}

/* Explicitly named container query */
@container table-widget (max-width: 550px) {
  .responsive-table thead {
    display: none;
  }
  
  .responsive-table td::before {
    content: attr(data-label);
    font-weight: 700;
  }
}

Container Query Units (CQ Units)

Container queries also introduce Container Query Length Units, which scale relative to the container's dimensions rather than the global viewport (vw/vh):

CQ Unit	Dimension Represented	Equivalent Viewport Unit
`1cqi`	$1%$ of the query container's inline size (width)	`1vw`
`1cqb`	$1%$ of the query container's block size (height)	`1vh`
`1cqw`	$1%$ of the query container's width	`1vw`
`1cqh`	$1%$ of the query container's height	`1vh`
`1cqmin`	Smaller value of `cqi` or `cqb`	`1vmin`
`1cqmax`	Larger value of `cqi` or `cqb`	`1vmax`

.table-cell {
  /* Dynamically scale padding based on parent container width */
  padding: clamp(8px, 1.5cqi, 20px);
  font-size: clamp(0.75rem, 1cqi + 0.5rem, 1rem);
}

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

Lines 49–54: .cq-table-wrapper establishes a container query boundary using container-type: inline-size; container-name: table-card;.
Lines 82–120: @container table-card (max-width: 460px) evaluates the width of the .cq-table-wrapper element itself, completely ignoring the global browser window width.
Lines 131–190: The exact same HTML markup is placed in both the wide main panel and the narrow sidebar panel.
Render Output: On a desktop monitor, the main panel displays a full 4-column table matrix, while the sidebar panel displays compact key-value cards, simultaneously on the same screen without custom JavaScript.

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

HTML STARSHIP CODE TERMINAL playground.html

<!DOCTYPE html>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1.0">
  <title>Container Query Responsive Table Widget</title>
  <style>
    * {
      box-sizing: border-box;
      margin: 0;
      padding: 0;
    }
    body {
      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;
      padding: 24px;
      background: #0f172a;
      color: #f8fafc;
    }

h1 {
      margin-bottom: 20px;
      font-size: 1.5rem;
      color: #38bdf8;
    }

/* Dashboard Layout: Wide Area + Narrow Sidebar */
    .dashboard-layout {
      display: grid;
      grid-template-columns: 2fr 1fr;
      gap: 24px;
    }

@media (max-width: 800px) {
      .dashboard-layout {
        grid-template-columns: 1fr;
      }
    }

.widget-panel {
      background: #1e293b;
      border: 1px solid #334155;
      border-radius: 12px;
      padding: 20px;
    }

.widget-title {
      font-size: 1rem;
      margin-bottom: 16px;
      color: #94a3b8;
      text-transform: uppercase;
      letter-spacing: 0.05em;
    }

/* =================================================== */
    /* CONTAINER QUERY COMPONENT DEFINITION                */
    /* =================================================== */
    
    /* 1. Define Container Context */
    .cq-table-wrapper {
      container-type: inline-size;
      container-name: table-card;
      width: 100%;
    }

/* 2. Default (Wide Container) Table Styles */
    .cq-table {
      width: 100%;
      border-collapse: collapse;
      font-size: 0.875rem;
    }

.cq-table th, 
    .cq-table td {
      padding: 10px 14px;
      text-align: left;
      border-bottom: 1px solid #334155;
    }

.cq-table th {
      background: #0f172a;
      color: #94a3b8;
      font-weight: 600;
    }

.badge {
      display: inline-block;
      padding: 3px 8px;
      border-radius: 9999px;
      font-size: 0.75rem;
      font-weight: 700;
    }
    .badge-success { background: #065f46; color: #34d399; }
    .badge-pending { background: #854d0e; color: #fde047; }

/* 3. Container-Driven Card Reflow when Parent Width <= 460px */
    @container table-card (max-width: 460px) {
      .cq-table,
      .cq-table tbody,
      .cq-table tr,
      .cq-table td {
        display: block;
        width: 100%;
      }

.cq-table thead {
        display: none;
      }

.cq-table tr {
        background: #0f172a;
        border: 1px solid #334155;
        border-radius: 8px;
        margin-bottom: 12px;
        padding: 8px 12px;
      }

.cq-table td {
        display: flex;
        justify-content: space-between;
        align-items: center;
        padding: 6px 0;
        border-bottom: 1px solid #1e293b;
        font-size: 0.8125rem;
      }

.cq-table td:last-child {
        border-bottom: none;
      }

.cq-table td::before {
        content: attr(data-label);
        font-weight: 600;
        color: #64748b;
        font-size: 0.75rem;
        text-transform: uppercase;
      }
    }
  </style>
</head>
<body>

<h1>Dashboard Telemetry Matrix (Single Viewport, Multi-Context)</h1>

<div class="dashboard-layout">
    
    
    <section class="widget-panel">
      <h2 class="widget-title">Main Processing Queue (Wide Container)</h2>
      <div class="cq-table-wrapper">
        <table class="cq-table" role="table">
          <thead role="rowgroup">
            <tr role="row">
              <th role="columnheader">Task ID</th>
              <th role="columnheader">Process Name</th>
              <th role="columnheader">Worker Node</th>
              <th role="columnheader">Status</th>
            </tr>
          </thead>
          <tbody role="rowgroup">
            <tr role="row">
              <td role="cell" data-label="Task ID"><strong>#TSK-801</strong></td>
              <td role="cell" data-label="Process Name">ETL Pipeline Sync</td>
              <td role="cell" data-label="Worker Node">node-us-east-1</td>
              <td role="cell" data-label="Status"><span class="badge badge-success">Running</span></td>
            </tr>
            <tr role="row">
              <td role="cell" data-label="Task ID"><strong>#TSK-802</strong></td>
              <td role="cell" data-label="Process Name">Database Vacuum</td>
              <td role="cell" data-label="Worker Node">node-eu-west-2</td>
              <td role="cell" data-label="Status"><span class="badge badge-pending">Queued</span></td>
            </tr>
          </tbody>
        </table>
      </div>
    </section>

<aside class="widget-panel">
      <h2 class="widget-title">Sidebar Queue (Narrow Container)</h2>
      <div class="cq-table-wrapper">
        <table class="cq-table" role="table">
          <thead role="rowgroup">
            <tr role="row">
              <th role="columnheader">Task ID</th>
              <th role="columnheader">Process Name</th>
              <th role="columnheader">Worker Node</th>
              <th role="columnheader">Status</th>
            </tr>
          </thead>
          <tbody role="rowgroup">
            <tr role="row">
              <td role="cell" data-label="Task ID"><strong>#TSK-901</strong></td>
              <td role="cell" data-label="Process Name">Redis Cache Flush</td>
              <td role="cell" data-label="Worker Node">cache-ap-1</td>
              <td role="cell" data-label="Status"><span class="badge badge-success">Running</span></td>
            </tr>
            <tr role="row">
              <td role="cell" data-label="Task ID"><strong>#TSK-902</strong></td>
              <td role="cell" data-label="Process Name">Log Aggregation</td>
              <td role="cell" data-label="Worker Node">log-collector-4</td>
              <td role="cell" data-label="Status"><span class="badge badge-pending">Queued</span></td>
            </tr>
          </tbody>
        </table>
      </div>
    </aside>

</div>

</body>
</html>

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Container-Aware Currency Conversion Table

Instructions:

Create a container query context on .currency-widget using container-type: inline-size.
Write a container query that transforms the table into vertical stacked cards when the container width drops below 400px.
Use the cqi unit to make cell padding dynamically scale smoothly between 6px and 16px.

🏁 Starter Code Sandbox

SYS: ACTIVE

HULL: 98%

CORE: STABLE

NET: ONLINE

STARTER CODE SANDBOX exercise.html

LIVE RENDER & DIAGNOSTICS CORE TEMP: 45°C

INSPECTING DOM: VALID

TAGS: SCANNING...

<style>
  /* 1. Establish Container Context */
  .currency-widget {
    container-type: inline-size;
    container-name: currency-box;
    width: 100%;
    font-family: system-ui, sans-serif;
  }

  table {
    width: 100%;
    border-collapse: collapse;
  }

  th, td {
    padding: clamp(8px, 2cqi, 16px); /* Fluid CQI padding */
    text-align: left;
    border-bottom: 1px solid #e2e8f0;
  }

  th {
    background-color: #f1f5f9;
    font-weight: 600;
  }

  /* 2. Container Query Reflow */
  @container currency-box (max-width: 400px) {
    table, tbody, tr, td {
      display: block;
      width: 100%;
    }

    thead {
      display: none;
    }

    tr {
      margin-bottom: 12px;
      border: 1px solid #cbd5e1;
      border-radius: 6px;
      padding: 8px;
    }

    td {
      display: flex;
      justify-content: space-between;
      align-items: center;
      padding: 6px 0;
      border-bottom: 1px solid #f1f5f9;
    }

    td:last-child {
      border-bottom: none;
    }

    td::before {
      content: attr(data-label);
      font-weight: 600;
      color: #64748b;
    }
  }
</style>

<div class="currency-widget">
  <table role="table">
    <thead role="rowgroup">
      <tr role="row">
        <th role="columnheader">Currency</th>
        <th role="columnheader">Exchange Rate (USD)</th>
        <th role="columnheader">24h Change</th>
      </tr>
    </thead>
    <tbody role="rowgroup">
      <tr role="row">
        <td role="cell" data-label="Currency"><strong>EUR (Euro)</strong></td>
        <td role="cell" data-label="Exchange Rate">1.0924</td>
        <td role="cell" data-label="24h Change">+0.42%</td>
      </tr>
      <tr role="row">
        <td role="cell" data-label="Currency"><strong>GBP (Pound)</strong></td>
        <td role="cell" data-label="Exchange Rate">1.2810</td>
        <td role="cell" data-label="24h Change">-0.15%</td>
      </tr>
    </tbody>
  </table>
</div>

Why this works:

Declaring container-type: inline-size isolates the table component from viewport dependencies.
The widget adapts automatically whether placed in a narrow mobile screen, an iPad split-view pane, or a desktop dashboard sidebar.

⚠️ Common Pitfalls

Applying @container queries directly to the container element: A query container cannot query itself. @container queries apply to children of the element declared with container-type.
Using container-type: size when height is unconstrained: container-type: size requires both width and height containment, which causes height to collapse to 0px if not explicitly defined. Always use container-type: inline-size for responsive tables.

💡 Pro Tips

Component-Driven Design Systems: Modern design systems (like Tailwind v3.4+ and Web Components) standardize on container queries so tabular UI components remain fully responsive in modals, drawers, tabs, and nested dashboard grids.
Browser Support: Container queries have 100% universal support across all modern evergreen browsers (Chrome 105+, Safari 16+, Firefox 110+, Edge 105+).

📌 Key Takeaways

Viewport media queries fail when table components are placed inside narrow containers on wide screens.
container-type: inline-size creates a horizontal query context on a parent element.
@container (max-width: ...) triggers styles based on the container's width, enabling true component-driven responsiveness.
Container query units (cqi, cqw) allow fluid typography and padding that scale relative to the container box.
--

⭐ LEARN: HTML 🌟 ⚔️ QUIZ BATTLE ARENA // ACTIVE

? Question 1 / 3

Why is `container-type: inline-size` preferred over `container-type: size` when designing responsive tables?

Topic: HTML Fundamentals

? Question 2 / 3

Can an element declared with `container-type: inline-size` query its own size inside an `@container` rule?

Topic: HTML Fundamentals

? Question 3 / 3

What does the container query unit `1cqi` represent?

Topic: HTML Fundamentals

👨‍🚀 CADET FLIGHT DOSSIER

CADET EXPLORER

📖 The Mental Model & Story (Intuitive Foundation)

Technical Deep Dive & Specifications

Establishing a Containment Context

The @container Rule Syntax

Container Query Units (CQ Units)

💻 Interactive Code Playground

Starter Code

Line-by-Line Code Breakdown

🏋️ Hands-On Exercise

🎯 The Challenge: Build a Container-Aware Currency Conversion Table

🏁 Starter Code Sandbox

⚠️ Common Pitfalls

💡 Pro Tips

📌 Key Takeaways

Why is container-type: inline-size preferred over container-type: size when designing responsive tables?

Can an element declared with container-type: inline-size query its own size inside an @container rule?

What does the container query unit 1cqi represent?

The `@container` Rule Syntax

Why is `container-type: inline-size` preferred over `container-type: size` when designing responsive tables?

Can an element declared with `container-type: inline-size` query its own size inside an `@container` rule?

What does the container query unit `1cqi` represent?