Skip to main content
Beta: Front-End Checklist is currently in beta. Some issues are still being fixed. Thanks for your patience.
CSSMedium

Use container queries for component-level responsiveness

Use CSS container queries to make components respond to their own container's size rather than the viewport, enabling truly reusable responsive components.

Utilities
Quick take
Typical fix time 20 min
  • Container queries respond to the parent container's size, not the viewport
  • Set container-type: inline-size on the parent to enable container queries
  • Use @container rule to write styles that activate at container breakpoints
  • Container queries make components reusable in sidebars, grids, and full-width areas
Why it matters: Media queries respond to viewport width, which makes components context-dependent — a card designed for a 3-column grid might break when placed in a 2-column grid or a sidebar. Container queries solve this: a card can layout itself based on how much space its container gives it, making the component genuinely reusable in any layout context.

Rule Details

Container queries allow a component to adapt its layout based on the size of its containing element rather than the viewport. This makes components genuinely portable.

Code Example

/* 1. Define the container on the PARENT */
.card-container {
  container-type: inline-size;
  /* Optionally name it */
  container-name: card;
  /* Shorthand */
  container: card / inline-size;
}
 
/* 2. Query the container from the CHILD */
@container (min-width: 400px) {
  .card {
    display: flex;
    gap: 1.5rem;
  }
 
  .card__image {
    flex: 0 0 200px;
  }
}

Why It Matters

Media queries respond to viewport width, which makes components context-dependent — a card designed for a 3-column grid might break when placed in a 2-column grid or a sidebar. Container queries solve this: a card can layout itself based on how much space its container gives it, making the component genuinely reusable in any layout context.

Named Containers

/* Name containers to target specific ancestors */
.sidebar {
  container: sidebar / inline-size;
}
 
.main-content {
  container: main / inline-size;
}
 
/* Target the sidebar container specifically */
@container sidebar (max-width: 300px) {
  .widget {
    font-size: 0.875rem;
  }
}
 
@container main (min-width: 800px) {
  .article {
    column-count: 2;
  }
}

Real-World Card Component

/* The card works anywhere — sidebar, grid, full-width */
.card-wrapper {
  container-type: inline-size;
}
 
.card {
  /* Stacked layout by default (narrow context) */
  display: grid;
  gap: 1rem;
}
 
.card__image {
  aspect-ratio: 16 / 9;
}
 
/* Side-by-side layout when there's enough room */
@container (min-width: 480px) {
  .card {
    grid-template-columns: 200px 1fr;
    align-items: start;
  }
 
  .card__image {
    aspect-ratio: 1;
  }
}
 
/* Richer layout at wide sizes */
@container (min-width: 720px) {
  .card {
    grid-template-columns: 320px 1fr;
  }
 
  .card__meta {
    display: flex;
    gap: 1rem;
  }
}

container-type Values

container-type: normal;       /* Default — not a container */
container-type: inline-size;  /* Queries based on inline (usually width) dimension */
container-type: size;         /* Queries based on both inline and block dimensions */

Container Units

/* Relative to the nearest container */
.responsive-text {
  font-size: clamp(1rem, 4cqi, 2rem);
  /* cqi = 1% of container's inline size */
  /* cqb = 1% of container's block size */
  /* cqw, cqh = same but always width/height */
  /* cqmin, cqmax = minimum/maximum of the two */
}

Support Notes

  • The feature is supported across the current project browser matrix.
  • Baseline-compatible minimums: chrome 115, edge 115, firefox 116, safari 16.4, safari_ios 16.4.
  • Add a fallback or progressive-enhancement note when a required project target falls outside that support range.

Verification

  1. Inspect the rendered UI at the breakpoints and interaction states affected by the rule.
  2. Confirm the computed styles match the intended fix in DevTools.
  3. Test at least one mobile and one desktop viewport before shipping.
  4. If the rule affects motion, contrast, or layout stability, verify those user-facing outcomes directly.

Use with AI

Copy these prompts to use with your AI assistant, or install the MCP server to use directly from Claude, Cursor, or Windsurf.

Check

Verify implementation

Look for components in this CSS that have media query breakpoints — consider whether container queries would make them more reusable in different layout contexts.

Fix

Auto-fix issues

Convert this component from media query-based to container query-based responsiveness using container-type and @container.

Explain

Learn more

Explain how container queries differ from media queries, why they enable better component reuse, and how to set up the container/query relationship.

Review

Code review

Review stylesheets, component styles, and responsive states related to Use container queries for component-level responsiveness. Flag exact selectors, declarations, or breakpoints that violate the rule in the rendered UI.

Sources

References used to support the guidance in this rule.

Further Reading

Tools and supplementary material for exploring the topic in more depth.

MDN Container queriesdeveloper.mozilla.orgTool

Rules that often go hand-in-hand with this one.

Use CSS containment to limit repaint scope

Apply the contain property to components to tell the browser they are independent from the rest of the page, enabling rendering optimizations that reduce repaint and reflow scope.

CSS
Use CSS Grid for two-dimensional layouts

Use CSS Grid when you need to control both rows and columns simultaneously, such as page layouts, card grids, and complex component arrangements.

CSS
Use relative units for responsive layouts

Use rem, em, %, vw, vh, and clamp() instead of fixed px values to build layouts that scale with user font size preferences and viewport dimensions.

CSS
Prevent horizontal scrolling

Web pages must not require horizontal scrolling at standard viewport widths. Horizontal overflow breaks responsive layouts and makes content inaccessible to low-vision users who zoom in.

CSS

Was this rule helpful?

Your feedback helps improve rule quality. This stays internal for now.

Loading feedback...
0 / 385