📦 Container Queries

Style components based on their parent container, not the viewport

📚 Theory: What Are Container Queries?

The Problem with Media Queries

Media queries look at the viewport (browser window size). This works for page layout, but fails when you have a component that needs to behave differently depending on WHERE it is placed on the page.

Example Problem

Imagine a product card that should be horizontal in the main content but vertical in the sidebar. Media queries cannot detect that the card is in a narrow sidebar — they only know the screen size is 1200px.

The Solution: Container Queries

Container queries look at the parent element's size, not the viewport. This means a component can adapt to its container, making it truly reusable.

          /* Step 1: Define a container */ .card-container { container-type:
          inline-size; container-name: my-container; } /* Step 2: Write a
          container query */ @container my-container (min-width: 500px) { .card
          { display: flex; } }
        

Browser Support (2026)

Chrome: 109+ (2023) ✅
Safari: 16.4+ (2023) ✅
Firefox: 110+ (2023) ✅

All modern browsers support container queries. You can use them today!

1. Same Card, Different Containers

The same card component is placed in two different containers. Resize your browser to see how the card changes based on its container width!

🖼️

Main Content Card

This container is wide, so the card becomes horizontal (row) using container query!

💡 Notice: The card in the sidebar is vertical. The card in the main content is horizontal. Same HTML, same CSS, different containers — different layouts. This is impossible with media queries!

          /* Step 1: Define the container */ .card-container { container-type:
          inline-size; container-name: card-container; } /* Step 2: Default
          style (mobile/vertical) */ .card { display: flex; flex-direction:
          column; } /* Step 3: Container query for wide containers */ @container
          card-container (min-width: 400px) { .card { display: flex;
          flex-direction: row; } }
        

2. One Component, Three Containers

Same card component placed in three different sized containers. Each card adapts to its container.

🖼️

Narrow

Under 400px → vertical layout

🖼️

Medium

400px to 600px → horizontal layout, small image

🖼️

Wide

600px+ → horizontal layout, larger image, bigger text

          @container card-container (min-width: 400px) { .card { display: flex;
          flex-direction: row; } .card-img { min-width: 150px; } } @container
          card-container (min-width: 600px) { .card-img { min-width: 200px; }
          .card-title { font-size: 1.25rem; } }
        

3. Media Query vs Container Query

❌ Media Query

              /* Looks at VIEWPORT (screen size) */ @media (min-width: 768px) {
              .card { display: flex; } } /* Problem: Card in sidebar and card in
              main content behave the same way */
            

✅ Container Query

              /* Looks at PARENT CONTAINER */ .card-container { container-type:
              inline-size; } @container (min-width: 400px) { .card { display:
              flex; } } /* Card adapts to its container! Sidebar card stays
              vertical, Main card becomes horizontal */
            

4. Practical Use Cases

Product cards — vertical in sidebar, horizontal in main content
Navigation menus — vertical in mobile drawer, horizontal in header
Dashboard widgets — different layouts based on widget size
Email components — adapt to different email clients
Design systems — truly reusable components

          /* Example: Responsive navigation that adapts to its container */
          .nav-container { container-type: inline-size; } .nav-list { display:
          flex; flex-direction: column; gap: 0.5rem; } @container (min-width:
          500px) { .nav-list { flex-direction: row; gap: 1rem; } }
        

⚡ Quick Reference Card

          /* =================================== STEP 1: DEFINE A CONTAINER
          =================================== */ .container { container-type:
          inline-size; /* Required */ container-name: my-container; /* Optional,
          for specificity */ } /* =================================== STEP 2:
          WRITE CONTAINER QUERY =================================== */
          @container (min-width: 400px) { /* Styles apply when container ≥ 400px
          */ } /* With named container */ @container my-container (min-width:
          500px) { } /* =================================== CONTAINER TYPES
          =================================== */ container-type: inline-size; /*
          Most common — width only */ container-type: size; /* Width AND height
          */ container-type: normal; /* No container queries */ /*
          =================================== MEDIA QUERY vs CONTAINER QUERY
          =================================== */ /* Media Query — based on
          viewport */ @media (min-width: 768px) { } /* Container Query — based
          on parent */ @container (min-width: 400px) { } /* Use BOTH together!
          */ /* Container queries for components, media queries for page layout
          */
        

📊 Summary

Container queries style components based on parent size
Media queries style pages based on viewport size
Use both together — media queries for layout, container queries for components
container-type: inline-size is what you need most of the time
Supported in all modern browsers — safe to use today