Container Queries for Reusable Components

Build a tutorial card that responds to the space it lives in, not just the size of the browser window.

Media Queries Look Outward. Container Queries Look Nearby.

A media query responds to the viewport, device, or user preference. A container query responds to an ancestor container around the component. That small shift changes how reusable CSS feels.

Instead of writing one set of rules for a card in the main layout and another set for the same card in a sidebar, you can teach the card how to respond to the space it actually has.

What You Will Build

You will build one reusable tutorial card component. The same card will appear in three places:

1. a narrow sidebar
2. a standard tutorial grid
3. a featured wide area

The component will have a narrow stacked layout, a medium state with more comfortable spacing, and a wide horizontal layout when the container has enough room.

Starter HTML

Start with three different layout areas. Each one uses the same .tutorial-card component inside a .card-container wrapper.

<section class="demo-layout">
  <aside class="sidebar-card-zone">
    <h2>Sidebar</h2>
    <div class="card-container">
      <article class="tutorial-card">
        <img src="/images/css-layout.jpg" alt="CSS layout sketch" />
        <div class="tutorial-card__content">
          <p class="tutorial-card__level">Intermediate CSS</p>
          <h3>Container Queries for Reusable Components</h3>
          <p>Learn how components can respond to the space they live in.</p>
          <a href="#">Start tutorial</a>
        </div>
      </article>
    </div>
  </aside>

  <main class="main-card-zone">
    <h2>Tutorial Grid</h2>
    <div class="tutorial-grid">
      <div class="card-container">
        <article class="tutorial-card">
          <img src="/images/css-layout.jpg" alt="CSS layout sketch" />
          <div class="tutorial-card__content">
            <p class="tutorial-card__level">Intermediate CSS</p>
            <h3>Container Queries for Reusable Components</h3>
            <p>Learn how components can respond to the space they live in.</p>
            <a href="#">Start tutorial</a>
          </div>
        </article>
      </div>

      <div class="card-container">
        <article class="tutorial-card">
          <div class="tutorial-card__content">
            <p class="tutorial-card__level">Intermediate CSS</p>
            <h3>Modern CSS Architecture</h3>
            <p>Organise your CSS so it stays readable as your site grows.</p>
            <a href="#">Start tutorial</a>
          </div>
        </article>
      </div>
    </div>
  </main>

  <section class="featured-card-zone">
    <h2>Featured Tutorial</h2>
    <div class="card-container card-container--featured">
      <article class="tutorial-card">
        <img src="/images/css-layout.jpg" alt="CSS layout sketch" />
        <div class="tutorial-card__content">
          <p class="tutorial-card__level">Intermediate CSS</p>
          <h3>Breaking Layouts Into Reusable Components Without Chaos</h3>
          <p>
            Learn how to turn layout sections into reusable patterns that can move
            around your site without breaking.
          </p>
          <a href="#">Start tutorial</a>
        </div>
      </article>
    </div>
  </section>
</section>

Base CSS

Add the basic page and layout styling first. This gives the example a readable structure before the component starts responding to its container.

*,
*::before,
*::after {
  box-sizing: border-box;
}

body {
  margin: 0;
  font-family: system-ui, sans-serif;
  line-height: 1.5;
  color: #1f1f1f;
  background: #f7f4ef;
}

img {
  max-width: 100%;
  display: block;
}

a {
  color: currentColor;
  font-weight: 700;
}

.demo-layout {
  width: min(100% - 2rem, 72rem);
  margin-inline: auto;
  padding-block: clamp(2rem, 6vw, 5rem);
  display: grid;
  gap: 2rem;
}

.sidebar-card-zone,
.main-card-zone,
.featured-card-zone {
  padding: 1rem;
  border: 1px solid #ddd3c7;
  border-radius: 1rem;
  background: #fffaf4;
}

.tutorial-grid {
  display: grid;
  gap: 1rem;
  grid-template-columns: repeat(auto-fit, minmax(min(16rem, 100%), 1fr));
}

Then add the default card styling:

.tutorial-card {
  overflow: hidden;
  border: 1px solid #d8cec1;
  border-radius: 1rem;
  background: white;
}

.tutorial-card img {
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

.tutorial-card__content {
  display: grid;
  gap: 0.75rem;
  padding: 1rem;
}

.tutorial-card__content > * {
  margin: 0;
}

.tutorial-card__level {
  font-size: 0.8rem;
  font-weight: 700;
  text-transform: uppercase;
  letter-spacing: 0.08em;
}

At this point, the card is reusable, but it does not yet know how much space it has. That is what container queries will add.

Why Media Queries Are Not Enough for Reusable Components

A media query responds to the viewport:

@media (min-width: 50rem) {
  .tutorial-card {
    display: grid;
    grid-template-columns: 1fr 2fr;
  }
}

This says that when the browser is at least 50rem wide, every tutorial card becomes horizontal. That might work on one page. It starts to wobble when one of those cards is inside a narrow sidebar.

The browser is wide, so the media query applies. The sidebar is narrow, so the card gets squashed. The problem is not that media queries are bad. The problem is that the viewport is not always the thing the component needs to respond to.

Step 1: Create a Query Container with container-type

Before you can query a container, tell the browser which element should behave as a query container:

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

This creates a containment context based on the container's inline-size. In most English-language layouts, that means horizontal width.

Use container-type: inline-size most of the time for cards, panels, lists, and navigation components. It means "watch this container's width." The broader size value watches both inline and block dimensions, which is useful less often and can be more restrictive.

Step 2: Use @container

Once a query container exists, use @container to apply styles when that container reaches a certain size:

@container (min-width: 32rem) {
  .tutorial-card {
    display: grid;
    grid-template-columns: 1fr 2fr;
  }

  .tutorial-card img {
    height: 100%;
    aspect-ratio: auto;
  }
}

The browser is not checking the viewport here. It is checking the nearest ancestor with a containment context. Now the same card can be stacked in a narrow sidebar and horizontal in a wider feature area.

Same component. Different container. Better behaviour.

Step 3: Add Component Variants

Components do not need to jump from tiny to huge. You can create smaller layout adjustments first:

@container (min-width: 22rem) {
  .tutorial-card__content {
    padding: 1.25rem;
  }

  .tutorial-card h3 {
    font-size: 1.35rem;
  }
}

Then add the larger layout change:

@container (min-width: 36rem) {
  .tutorial-card {
    display: grid;
    grid-template-columns: minmax(12rem, 0.8fr) 1.2fr;
  }

  .tutorial-card img {
    height: 100%;
    aspect-ratio: auto;
  }

  .tutorial-card__content {
    align-content: center;
  }
}

The narrow state stays as the default. The medium state adds breathing room. The wide state becomes horizontal. This is the real power of container queries: the component becomes responsive to its own available space.

Step 4: Named Containers

So far, the @container rule uses the nearest available query container. That is fine for many components. Sometimes, especially in nested layouts, you may want to target a specific container.

.card-container {
  container-name: tutorial-card;
  container-type: inline-size;
}

/* Shorthand version */
.card-container {
  container: tutorial-card / inline-size;
}

@container tutorial-card (min-width: 36rem) {
  .tutorial-card {
    display: grid;
    grid-template-columns: minmax(12rem, 0.8fr) 1.2fr;
  }
}

Named containers are useful when components are nested, several parent elements have container-type, or you want to be explicit about which container controls the style.

For this lesson, use container: tutorial-card / inline-size. It is compact and clear.

Step 5: Container Query Units

Container query units are length units based on the query container. They are similar in spirit to viewport units like vw and vh, except they relate to the container instead of the browser window.

For most component work, start with cqi:

.tutorial-card h3 {
  font-size: clamp(1.1rem, 5cqi, 1.6rem);
}

.tutorial-card__content {
  padding: clamp(1rem, 4cqi, 1.75rem);
}

This makes text and spacing feel more naturally responsive inside different layout areas. Not because the page changed. Because the component's own available space changed.

Step 6: Final Component CSS

Here is the finished version of the component CSS:

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

.tutorial-card {
  overflow: hidden;
  border: 1px solid #d8cec1;
  border-radius: 1rem;
  background: white;
}

.tutorial-card img {
  width: 100%;
  aspect-ratio: 16 / 9;
  object-fit: cover;
}

.tutorial-card__content {
  display: grid;
  gap: 0.75rem;
  padding: clamp(1rem, 4cqi, 1.75rem);
}

.tutorial-card__content > * {
  margin: 0;
}

.tutorial-card__level {
  font-size: 0.8rem;
  font-weight: 700;
  text-transform: uppercase;
  letter-spacing: 0.08em;
}

.tutorial-card h3 {
  font-size: clamp(1.1rem, 5cqi, 1.6rem);
  line-height: 1.15;
}

.tutorial-card a {
  justify-self: start;
}

@container tutorial-card (min-width: 22rem) {
  .tutorial-card__content {
    gap: 1rem;
  }
}

@container tutorial-card (min-width: 36rem) {
  .tutorial-card {
    display: grid;
    grid-template-columns: minmax(12rem, 0.8fr) 1.2fr;
  }

  .tutorial-card img {
    height: 100%;
    aspect-ratio: auto;
  }

  .tutorial-card__content {
    align-content: center;
  }

  .tutorial-card:not(:has(img)) {
    display: block;
  }
}

Media Queries vs Container Queries

Media queries are not wrong. They are still useful. The trick is knowing which question you are asking.

Example media query:

@media (min-width: 60rem) {
  .demo-layout {
    grid-template-columns: 16rem 1fr;
  }

  .featured-card-zone {
    grid-column: 1 / -1;
  }
}

Example container query:

@container tutorial-card (min-width: 36rem) {
  .tutorial-card {
    grid-template-columns: minmax(12rem, 0.8fr) 1.2fr;
  }
}

Use both. Just do not ask media queries to solve every component problem. That is how stylesheets become a cupboard full of mystery cables.

Common Mistakes and Defensive Testing

Reusable components often receive imperfect content. A component that only works with perfect demo copy is not reusable yet.

Common mistakes

• Forgetting container-type: without an eligible query container, the browser has nothing useful to query.
• Putting the container on the wrong element: container queries style descendants, so a wrapper is usually clearer.
• Using container queries for everything: page-level layout decisions still belong with media queries.
• Forgetting narrow states: start with the safe stacked layout, then enhance it.
• Not testing missing content: cards without images or descriptions should still look intentional.

Defensive test cases

Add these cases to your HTML:

<h3>
  Understanding Container Queries When Your Component Lives Somewhere Deeply
  Inconvenient
</h3>

<article class="tutorial-card">
  <div class="tutorial-card__content">
    <p class="tutorial-card__level">Intermediate CSS</p>
    <h3>Modern CSS Architecture</h3>
    <p>Organise your CSS so your future self does not quietly resent you.</p>
    <a href="#">Start tutorial</a>
  </div>
</article>

<article class="tutorial-card">
  <img src="/images/css-layout.jpg" alt="CSS layout sketch" />
  <div class="tutorial-card__content">
    <p class="tutorial-card__level">Intermediate CSS</p>
    <h3>Subgrid and Layout Alignment</h3>
    <a href="#">Start tutorial</a>
  </div>
</article>

Then test the same component in different container widths:

.test-narrow {
  width: 14rem;
}

.test-medium {
  width: 24rem;
}

.test-wide {
  width: 44rem;
}

If a no-image card looks odd in the wide layout, add a defensive rule:

@container tutorial-card (min-width: 36rem) {
  .tutorial-card:not(:has(img)) {
    display: block;
  }
}

Guided Practice

Independent Practice