CSS Container Queries: Syntax, Usage, and Examples

CSS container queries enable elements to adapt their styling based on the size of their container rather than the size of the viewport. This breakthrough feature allows developers to build fully modular and responsive components that behave predictably in any layout context, enhancing the reusability and maintainability of front-end code.

What Are CSS Container Queries?

CSS container queries allow you to apply styles to an element based on the dimensions of its containing block. This contrasts with traditional media queries, which rely on the dimensions of the entire viewport.

With container queries CSS functionality, you can:

• Build components that adapt based on where they are placed
• Make cards, widgets, and other UI blocks responsive without knowing the page’s layout
• Avoid unnecessary media queries tied to global breakpoints

This is a significant evolution in responsive design, especially for component-based frameworks like React, Vue, or Web Components.

Basic Syntax of CSS Container Queries

Using CSS container queries involves two steps:

1. Declaring a container
2. Writing styles that respond to the container’s size

Step 1: Declare a Container

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

This tells the browser to observe the inline size (width) of the element for container query purposes. You can also define a name:

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

Step 2: Write a Container Query

@container (min-width: 500px) {
  .card-content {
    font-size: 1.5rem;
  }
}

This applies the style only when the container is at least 500px wide.

Understanding Container Types

There are two container types available:

• size – Reacts to both block and inline dimensions.
• inline-size – Reacts only to width (most commonly used).

Use inline-size when you only need horizontal responsiveness, and size when height is also important.

.container {
  container-type: size;
}

You must also set a containment context on the container. This is automatically provided when you set container-type, but you can manually specify it using the shorthand:

.container {
  container: layout inline-size;
}

Real-World Examples of CSS Container Queries

Responsive Card Component

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

@container card (min-width: 600px) {
  .card-title {
    font-size: 2rem;
  }
  .card-layout {
    flex-direction: row;
  }
}

When .card is wider than 600px, it switches to a horizontal layout with larger text.

Sidebar with Dynamic Layout

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

@container (max-width: 300px) {
  .menu {
    flex-direction: column;
  }
}

The sidebar menu switches to vertical layout when it gets narrower.

Combining Container Queries with Flexbox and Grid

CSS container queries pair naturally with modern layout systems like Flexbox and Grid. You can structure a layout and use queries to adapt child elements based on available space.

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

@container (max-width: 700px) {
  .panel {
    grid-template-columns: 1fr;
  }
}

This switches a two-column layout to single-column when the container becomes narrow.

Nesting and Inheritance

Container queries can be nested within deeply structured components. This enables fine-grained control in component libraries.

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

@container (min-width: 400px) {
  .widget .title {
    font-size: 1.75rem;
  }
}

If .widget is placed inside a column, row, or modal, the style adapts based on local container width—not the full page.

Best Practices for Using CSS Container Queries

1. Use meaningful container names

   Names like sidebar, card, or widget make nested queries easier to manage.

2. Apply only where needed

   Don’t wrap the entire page in container contexts—reserve container-type for component wrappers to minimize layout recalculations.

3. Start with inline-size

   It’s simpler and widely supported. Only use size if vertical responsiveness is necessary.

4. Use clamp() for hybrid approaches

   Combine container queries with clamp() for smarter, scale-friendly typography.

5. Combine with media queries carefully

   You can mix both techniques to control global layout and local component behavior.

Limitations and Considerations

Browser Support

CSS container queries are supported in all modern browsers:

• Chrome (from v105)
• Edge (from v105)
• Safari (from v16)
• Firefox (from v110)

Always check compatibility before relying heavily on them for core layout features.

No Support for Non-Size Properties

Currently, container queries only work for physical size. You cannot query container color, scroll state, or child content count.

No Scroll Containers

Containers cannot be scrollable (overflow: auto) and act as a container query source at the same time. This restriction may be lifted in future browser updates.

Enhancing Component Libraries

Component libraries like Tailwind, Bootstrap, and Material UI can benefit from container queries for:

• Adaptive cards and buttons
• Responsive forms
• Conditional grid layouts
• Smart dropdowns and popovers

Instead of duplicating layout logic at the page level, components can independently manage their layout state.

Debugging Container Queries

Use DevTools (Chrome and Firefox) to inspect containers:

• Look for the “container” badge next to elements.
• Toggle different widths in the layout pane.
• Add breakpoints inside @container rules to test behavior.

Testing multiple placements of the same component in a responsive grid is key to understanding how CSS container queries will behave.

Container Queries in Design Systems

Design systems often require reusable, responsive components. Container queries make it easier to:

• Isolate component logic
• Build atomic layouts
• Design in Storybook without viewport-specific overrides
• Maintain clean separation between global layout and local logic

You can even simulate container-based responsiveness in design tools like Figma using layout constraints, ensuring better design-to-code fidelity.

CSS container queries mark a significant step forward in responsive design. By allowing components to style themselves based on their own size rather than the viewport, they promote true modularity, flexibility, and reusability in modern web development.