Modern CSS Layouts & Micro-InteractionsProduction-focused CSS patterns and architecture

Nesting and Naming Container Queries: Targeting the Right Ancestor

Problem statement

You build a product card whose inner media block should switch to a row layout when the card itself is wide, and you also wrap the whole card grid in a container so the grid can reflow. Now you have two query containers stacked above the media block, and a plain @container (min-width: 400px) rule silently binds to the closest one — the card — when you actually meant the outer grid, or vice versa. Worse, a beginner reflex is to put container-type on the same element you want to style, expecting it to react to its own width, which never fires. This guide, part of Container Query Syntax Basics under Mastering Container Queries & Responsive Layouts, shows how to name containers so each query resolves to exactly the ancestor you intend, and how to avoid the accidental self-query trap.

Approach rationale

The CSS containment model resolves an @container rule by walking up the ancestor chain from the styled element and stopping at the first element whose container-type makes it a valid query container for the requested axis. If the rule names a container with @container card (...), the walk stops at the nearest ancestor whose container-name includes card. This is deliberate and matches how the cascade resolves other contextual lookups, but it means naming is your only reliable control once containers nest. Relying on "nearest unnamed container" is fragile: any refactor that introduces a new container between the styled element and its intended target will silently rebind the query.

The alternative — using JavaScript to measure ancestors and apply classes — reintroduces the layout-read/style-write cycle container queries were designed to remove, and it is hard to keep accessible because the class flip can lag a frame behind the resize. Naming containers keeps the whole resolution in the engine's single layout pass. The accessibility tradeoff is minimal: names are invisible to assistive technology and add no DOM, so the only cost is the discipline of choosing stable, meaningful names.

Complete working implementation

Which named ancestor a query matches Nested containers named page and card; the @container card query resolves to the nearest ancestor carrying the card name, skipping page. Resolving @container card from a nested element container-name: page container-name: card ← match styled element (no container-type) @container card (min-width: 420px) walk stops at the nearest ancestor named card, never the page container
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<style>
  /* Outer container: lets the grid itself reflow with available space */
  .feed {
    container: page / inline-size; /* shorthand = container-name + container-type */
    display: grid;
    gap: 1.5rem;
    padding: 1.5rem;
  }

  /* When the feed is wide, show two columns of cards. Named so it binds to .feed only */
  @container page (min-width: 700px) {
    .feed {
      grid-template-columns: 1fr 1fr;
    }
  }

  /* Middle container: each card scopes its own internal layout */
  .card {
    container: card / inline-size;
    background: #11141c;
    color: #e8ecf4;
    border-radius: 12px;
    padding: 1rem;
  }

  /* The media block is the STYLED element. It carries NO container-type, */
  /* so it cannot query itself. The query below names `card`, so the walk  */
  /* up the tree stops at .card and ignores the outer .feed (page).        */
  .card__media {
    display: grid;
    gap: 0.75rem;
  }

  @container card (min-width: 420px) {
    .card__media {
      grid-template-columns: 140px 1fr; /* image beside text once the CARD is wide */
      align-items: center;
    }
  }

  .card__media img {
    width: 100%;
    border-radius: 8px;
    aspect-ratio: 4 / 3;
    object-fit: cover;
  }
</style>
</head>
<body>
  <div class="feed">
    <article class="card">
      <div class="card__media">
        <img src="https://placehold.co/280x210" alt="Sample product photo">
        <div>
          <h2>Named-container card</h2>
          <p>Its inner layout reacts to the card width, not the feed width.</p>
        </div>
      </div>
    </article>
    <article class="card">
      <div class="card__media">
        <img src="https://placehold.co/280x210" alt="Second product photo">
        <div>
          <h2>Second card</h2>
          <p>Same rules, resolved independently against its own card container.</p>
        </div>
      </div>
    </article>
  </div>
</body>
</html>

Key technique callout

The mechanism that prevents the accidental self-query is the separation between the container element and the styled element. container-type establishes a query container, but a container can never match a query that styles itself — the resolution always walks to an ancestor. So the working pattern is always: put container-type (or the container shorthand) on a wrapper, and write the conditional rule against a descendant. The second half of the technique is container-name. When containers nest, @container card (...) filters the ancestor walk to elements whose name list includes card, letting you skip an intervening unnamed or differently named container. Using the container: <name> / <type> shorthand sets both at once and is the most robust default, because it makes every container explicitly named and therefore impossible to bind to by accident.

Variation or extension

A container can answer to more than one name, which is useful for reduced-motion and theming variants that need to address the same box under different aliases. The container-name property accepts a space-separated list.

/* This container responds to BOTH `card` and `surface` queries */
.card {
  container-name: card surface;
  container-type: inline-size;
}

/* Generic surface rule, e.g. shared by cards, panels and tiles */
@container surface (min-width: 600px) {
  .card__media { gap: 1rem; }
}

/* Card-specific rule on the same element */
@container card (min-width: 420px) {
  .card__media { grid-template-columns: 140px 1fr; }
}

This lets a design-system primitive expose a stable generic name (surface) while a specific component layers its own name on top, so shared rules and component rules both resolve to the right box without duplicating containers.

Browser support note

Container names, the container shorthand, and named @container queries are part of the same size-query baseline: Chrome and Edge 105+, Safari 16.0+, and Firefox 110+. Multiple names in one container-name list and the shorthand are supported across all of these versions, so no separate fallback is needed beyond the static styles you already ship for engines without container queries at all — see the guide to feature detection with @supports.

FAQ

Can an element query its own size with a container query? No. A container query resolves against the nearest matching ancestor query container, never the element itself. To respond to an element's own width you must wrap it so the parent is the container, or split the component into a container wrapper and a styled child.

What does an unnamed @container query target? It targets the nearest ancestor that has a container-type, regardless of name. If you have several nested containers, an unnamed query binds to the closest one, which is often not the one you intended. Use container-name to bind explicitly.

Can two containers share the same container-name? Yes. A name is not required to be unique. When names collide, a query with that name still resolves to the nearest ancestor carrying it, so reuse the same name only for genuinely interchangeable containers.

Does container-type alone create a name? No. container-type makes an element a query container but leaves it anonymous. Add container-name, or use the container shorthand, to give it a name that @container queries can reference.

Related articles

More pages in the same section.