--- name: using-container-queries description: Use container queries for component-based responsive design with @container syntax and named containers. Use when building portable, reusable components that adapt to parent size instead of viewport. allowed-tools: Read, Write, Edit, Grep, Glob --- # Using Container Queries ## Purpose Container queries enable components to respond to their parent container's size instead of the viewport. This creates truly portable, reusable components that work anywhere. ## Basic Container Queries **Step 1: Mark the container** ```html
Card 1
Card 2
Card 3
Card 4
``` The `@container` class makes an element a container query context. **Step 2: Use container breakpoints** Container breakpoint utilities use `@` prefix: - `@sm:` - Container width ≥ 640px - `@md:` - Container width ≥ 768px - `@lg:` - Container width ≥ 1024px - `@xl:` - Container width ≥ 1280px - `@2xl:` - Container width ≥ 1536px ## Container vs Viewport Queries **Viewport queries (viewport width):** ```html
``` Responds to browser window width. **Container queries (parent width):** ```html
``` Responds to parent container width. ## Named Containers Use named containers for nested container queries: ```html
Main container responsive
Sidebar container responsive
``` **Syntax:** `@container/{name}` for the container, `@{breakpoint}/{name}:` for utilities. ## Portability Patterns ### Reusable Card Component ```html

Card Title

Card description that adapts to container size.

``` This card works in: - Full-width layouts - Sidebar layouts - Grid layouts - Any container size ### Dashboard Widget ```html

Widget Title

Stat 1
Stat 2
Stat 3
``` ### Responsive Navigation ```html
``` ## Complex Layout Example ```html

Card Title

Description that adapts based on available space in the card container.

2 days ago
``` ## Mixing Container and Viewport Queries You can combine both for maximum control: ```html
Components adapt to both viewport and container
``` **Order matters:** Viewport queries first, then container queries to override. ## Container Query Breakpoints Default container breakpoints: | Breakpoint | Min Width | | ---------- | --------- | | `@xs` | 320px | | `@sm` | 640px | | `@md` | 768px | | `@lg` | 1024px | | `@xl` | 1280px | | `@2xl` | 1536px | ## Custom Container Breakpoints Define custom container breakpoints in theme: ```css @theme { --container-xs: 20rem; --container-sm: 40rem; --container-md: 48rem; --container-lg: 64rem; --container-xl: 80rem; } ``` ## Performance Considerations Container queries are highly performant in modern browsers. They: - Use native browser APIs - Don't require JavaScript - Trigger efficient reflows - Work with CSS cascade layers ## Browser Support Container queries require: - Safari 16.4+ - Chrome 111+ - Firefox 128+ Same as Tailwind v4's minimum browser requirements. ## Best Practices 1. **Use for component portability** - Container queries excel at making components work anywhere 2. **Name containers when nested** - Use `/name` syntax for clarity 3. **Prefer container queries for components** - Use viewport queries for page-level layouts 4. **Combine with viewport queries** - Use both for maximum flexibility 5. **Test at various sizes** - Verify components work in narrow and wide containers ## Common Patterns ### Sidebar Layout ```html
Content 1
Content 2
``` ### Product Grid ```html

Product

$99

``` ### Form Layout ```html
``` ## See Also - RESEARCH.md sections: "Container Queries" and "Usage Patterns"