For years, responsive design meant one thing: the viewport. You wrote a media query, checked the browser width, and hoped your sidebar component looked good no matter where it landed. That approach works, but it breaks down fast in modern layouts. A card grid in a narrow aside needs different treatment than the same grid in a main content area. With container queries, you can finally ask the component itself, “How wide is your parent right now?” and style accordingly.

What makes container queries different

Media queries check the browser viewport. Container queries check the size of a parent element. That subtle shift changes everything.

Imagine you have a product card. In a three-column grid on a desktop, the card has room for a large image and a description. On a phone, that same card might sit in a single column. With media queries, you would write breakpoints based on the whole screen. But what if your card lives inside a sidebar that is only 300 pixels wide on a large monitor? Media queries see a wide viewport and apply large styles, even though the card is cramped.

Container queries solve this by letting the card ask, “How much space does my container actually give me?” The card becomes self-contained. It adapts to its parent, not the browser.

This is especially powerful for component libraries, design systems, and micro-frontends. You can build a component once and trust it will look right in any context. For more on building modular frontends, check out our guide on unlocking the power of web components for modern frontend development.

How the @container rule works

The syntax builds on three core properties:

• container-type: Declares that an element can be a query container. Use size to enable queries on the inline-size and block-size.
• container-name: Gives the container a label. This is optional but helpful for complex layouts with multiple containers.
• @container at-rule: The query itself. It works like @media but checks the container’s dimensions.

Here is a basic example:

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

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

@container card (max-width: 399px) {
  .card {
    display: flex;
    flex-direction: column;
  }
}

The .card-container div becomes a queryable container. The .card element inside it switches between a grid and a flex layout depending on the container’s width. The viewport width does not matter.

Setting up your first container query

Let’s build a profile card that adapts to its parent width. Follow these steps:

1. Pick a parent element that wraps your component. Give it container-type: inline-size. You can also set container-name to something descriptive like profile.

2. Write the default styles for your component. These should be the smallest layout or the mobile view. Container queries will override them when conditions are met.

3. Add your @container rules using the same name. Use standard min-width and max-width breakpoints. Inside each block, override only the properties that change.

4. Test the component in different contexts. Drop it into a narrow sidebar, a wide main area, and a medium column. The component should adjust automatically.

5. Refine the breakpoints based on real content. A profile card with a long bio might need a wider breakpoint than one with a short bio. Adjust until the layout feels natural.

Here is a complete example:

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

.profile-card {
  display: flex;
  flex-direction: column;
  gap: 8px;
}

@container profile (min-width: 500px) {
  .profile-card {
    flex-direction: row;
    align-items: center;
  }
}

@container profile (min-width: 800px) {
  .profile-card {
    flex-direction: row;
    align-items: flex-start;
    gap: 24px;
  }
}

The card stacks vertically below 500 pixels, switches to a row layout between 500 and 799 pixels, and adds more spacing above 800 pixels. All of this happens without a single media query.

Where container queries shine

Container queries are not a replacement for media queries. They solve a different problem. Here are the best use cases:

• Reusable components in a design system. A button group, a card, a navigation bar. These elements move between pages and layouts. Container queries make them context-aware.
• Dashboard widgets. A chart might display full data in a wide panel but show a summary in a narrow one. The widget can query its own container.
• Content blocks in a CMS. Editors can place blocks anywhere without breaking the layout. The block adapts to the column width.
• Micro-frontends. Each service owns its component. Container queries ensure the component fits its host page.

For a broader look at how these patterns fit into modern workflows, see our piece on 5 new CSS features that will change your workflow in 2026.

Common mistakes and how to avoid them

Container queries are new. It is easy to trip up. Here is a table of frequent pitfalls and their fixes.

Mistake	Why it happens	The fix
Forgetting container-type	The element is not a query container, so @container does nothing.	Always add container-type: inline-size to the parent.
Using viewport units inside queries	vw and vh refer to the viewport, not the container.	Use relative units like % or fixed values like px.
Nesting containers without names	Queries can target the wrong container.	Use container-name to be explicit.
Overriding too many properties	The component becomes hard to maintain.	Override only layout and spacing. Keep typography and colors in base styles.
Testing only in one context	The component might fail in a different parent.	Test in a narrow, medium, and wide container.

Expert advice: Start with one breakpoint. It is tempting to write four or five conditions, but two or three usually cover most scenarios. Let the content guide your breakpoints, not arbitrary pixel values.

Debugging container queries

Browser support for container queries is solid in 2026, but debugging them requires a slightly different mindset. The browser’s inspector shows the computed styles, but it does not always show which @container rule is active.

Here are a few techniques:

• Use a custom property as a signal. Set --container-state: narrow inside a @container rule and inspect the element to see which value is applied.
• Add a temporary border or background. Change the background color inside each breakpoint to visually confirm which rule is firing.
• Check the container element. Make sure it has container-type set. If the parent does not have it, the query will not work.
• Use the browser’s CSS panel. Look for the @container rules in the stylesheet. Some browsers show them in a separate section.

If you are working with complex animations alongside container queries, our tutorial on master modern web animations with CSS and JavaScript techniques can help you combine both approaches smoothly.

Combining container queries with other modern CSS

Container queries pair well with other CSS features that arrived in recent years.

• CSS Grid subgrid. You can nest grids and have container queries adjust the inner grid based on the outer grid’s column width.
• @scope rule. The new @scope rule limits styles to a subtree. Combined with container queries, you can create fully isolated components. Learn more in our article on why the new CSS @scope rule is the end of BEM naming conventions.
• light-dark() function. Container queries can trigger different themes based on container size. A wide container might use a light theme, while a narrow one uses a dark theme. See why the new CSS light-dark() function is a game-changer for theme management in 2026.

Here is a small example combining container queries with CSS Grid:

.dashboard-panel {
  container-type: inline-size;
  container-name: panel;
  display: grid;
  grid-template-columns: 1fr;
}

@container panel (min-width: 600px) {
  .dashboard-panel {
    grid-template-columns: 1fr 1fr;
  }
}

The panel starts as a single column. When the container reaches 600 pixels, it splits into two columns. The grid adapts to the space the panel actually occupies, not the viewport.

Performance considerations

Container queries are efficient. The browser only recalculates styles when the container’s size changes, which is similar to how media queries work. However, there are a few things to keep in mind:

• Avoid deep nesting of containers. A container inside a container inside a container can create a cascade of recalculations. Keep your container hierarchy shallow.
• Use container-type: inline-size instead of size unless you need block-size queries. Inline-size is cheaper because it only watches the width.
• Do not query on every pixel. Use reasonable breakpoints. A difference of 10 pixels is usually not worth a separate rule.

For more tips on optimizing your frontend workflow, check out our guide on how to optimize your front-end workflow with cutting-edge tools.

A practical checklist for your next project

Before you ship a component that uses container queries, run through this list:

• Does the parent element have container-type?
• Did you name the container if you have more than one?
• Are the breakpoints based on the container’s content, not the viewport?
• Did you test the component in at least three different parent widths?
• Are the default styles the smallest layout?
• Did you avoid overriding properties that do not need to change?

Container queries are still a relatively new tool. They will feel unfamiliar at first. But once you build a few components that adapt without media queries, you will wonder how you managed without them.

Where to go from here

Start small. Pick one reusable component in your current project a card, a button group, or a navigation bar. Wrap it in a container with container-type: inline-size and write two breakpoints. See how it behaves in different parts of your layout. Then expand from there.

Container queries are not a magic wand. They will not fix a poorly structured layout. But they will give your components independence. They will let you build UI modules that work everywhere, without guessing the viewport.

For a deeper look at how frontend frameworks are evolving alongside these CSS features, read our article on top trends in front-end frameworks for 2026.

Now go ahead and give your components the awareness they deserve. Write a container query today.