🏷️ container-name — Naming Containers for Precise Container Queries

🌐 What is container-name?

container-name is a CSS property used to give a container acustom name so that your @container queries can explicitly target it — instead of targeting any container in the ancestor chain.

>>“container-name gives you fine-grained control — you decide which container the query listens to.”

Note

✔ Works together with container-type. Without container-type, naming a container has no effect.

🎯 Why Use container-name?

  • To target specific containers in complex layouts
  • To avoid triggering queries from unintended parent containers
  • To create reusable, independent UI components
  • To make container queries clearer and more maintainable

📌 Syntax

container-name Syntax

container-name: myContainer;

A container can have **one or multiple names**:

Multiple names

container-name: layout card responsive;

🧱 Example 1 — Naming a Container

Define a Named Container

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

Now you can target this container specifically:

Query the Named Container

@container card-layout (min-width: 480px) {
  .card-title {
    font-size: 1.8rem;
  }
}

The query triggers ONLY when .card grows to 480px wide.

🧱 Example 2 — Using Multiple Named Containers

Multiple Names

.dashboard {
  container-type: inline-size;
  container-name: layout dashboard sidebar-area;
}

You can now write queries like:

Using Any Name

@container dashboard (min-width: 900px) {
  .sidebar { display: block; }
}

@container layout (min-width: 1200px) {
  .main-content { max-width: 1100px; }
}

Each name creates a separate “listen point” for responsive behavior.

📐 Visual Model

Media content

With naming, components react EXACTLY to the container you specify.

🧪 Example 3 — Combining container-type + container-name

Named Container with Type

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

@container profile (min-width: 400px) {
  .avatar { width: 150px; }
  .details { font-size: 1.2rem; }
}

Even if this card is nested inside other containers,only this specific container affects the component.

📱 Real-World Example — Reusable Components

Suppose you have multiple cards inside different grid layouts. Each card should react to its own space, not the page.

Reusable Card Component

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

@container card (min-width: 550px) {
  .card-body {
    display: flex;
    gap: 20px;
  }
}

This makes the card responsive in ANY layout where it’s placed.

🧠 How container-name Works Internally

ConceptBehavior
Without container-nameQuery matches the nearest container-type ancestor
With container-nameQuery matches ONLY the named container(s)
Multiple namesYou can match using any one of the declared names

Note

🧠 Use container-name when you want **precise control** in deeply nested layouts.

⚠️ Common Mistakes

  • Using container-name without container-type — does nothing
  • Misspelling the container name in @container queries
  • Naming too many containers unnecessarily
  • Assuming container-name affects layout (it doesn’t)

🔥 Summary

container-name is a powerful addition to container queries, enabling developers to precisely target containers in any layout. When combined with container-type, it unlocks fully modular, reusable, component-driven responsive design.

>>“With container-name, you control exactly which container drives the responsiveness.”

Learn more →MDN Docs 📘