Initial commit
This commit is contained in:
Zhongwei Li
309
skills/using-container-queries/SKILL.md
Normal file
309
skills/using-container-queries/SKILL.md
Normal file
@@ -0,0 +1,309 @@
|
||||
---
|
||||
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
|
||||
<div class="@container">
|
||||
<div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-4 gap-4">
|
||||
<div>Card 1</div>
|
||||
<div>Card 2</div>
|
||||
<div>Card 3</div>
|
||||
<div>Card 4</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
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
|
||||
<div class="grid-cols-1 md:grid-cols-2 lg:grid-cols-3"></div>
|
||||
```
|
||||
|
||||
Responds to browser window width.
|
||||
|
||||
**Container queries (parent width):**
|
||||
|
||||
```html
|
||||
<div class="@container">
|
||||
<div class="grid-cols-1 @md:grid-cols-2 @lg:grid-cols-3"></div>
|
||||
</div>
|
||||
```
|
||||
|
||||
Responds to parent container width.
|
||||
|
||||
## Named Containers
|
||||
|
||||
Use named containers for nested container queries:
|
||||
|
||||
```html
|
||||
<div class="@container/main">
|
||||
<div class="@container/sidebar">
|
||||
<div class="flex flex-col @sm/main:flex-row">
|
||||
Main container responsive
|
||||
</div>
|
||||
|
||||
<div class="text-sm @md/sidebar:text-base">
|
||||
Sidebar container responsive
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**Syntax:** `@container/{name}` for the container, `@{breakpoint}/{name}:` for utilities.
|
||||
|
||||
## Portability Patterns
|
||||
|
||||
### Reusable Card Component
|
||||
|
||||
```html
|
||||
<div class="@container">
|
||||
<article class="bg-white rounded-lg shadow-md p-4 @md:p-6">
|
||||
<div class="flex flex-col @md:flex-row @md:gap-6">
|
||||
<img class="w-full @md:w-48 rounded-lg" src="/image.jpg" />
|
||||
|
||||
<div class="flex-1 mt-4 @md:mt-0">
|
||||
<h2 class="text-lg @md:text-xl @lg:text-2xl font-bold">Card Title</h2>
|
||||
|
||||
<p class="mt-2 text-sm @md:text-base text-gray-600">
|
||||
Card description that adapts to container size.
|
||||
</p>
|
||||
|
||||
<button class="mt-4 px-3 py-1.5 @md:px-4 @md:py-2 bg-blue-600 text-white rounded-md">
|
||||
Read More
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
</article>
|
||||
</div>
|
||||
```
|
||||
|
||||
This card works in:
|
||||
- Full-width layouts
|
||||
- Sidebar layouts
|
||||
- Grid layouts
|
||||
- Any container size
|
||||
|
||||
### Dashboard Widget
|
||||
|
||||
```html
|
||||
<div class="@container">
|
||||
<div class="bg-white rounded-lg p-4">
|
||||
<div class="flex items-center justify-between">
|
||||
<h3 class="text-base @md:text-lg font-semibold">Widget Title</h3>
|
||||
<button class="text-xs @md:text-sm text-blue-600">View All</button>
|
||||
</div>
|
||||
|
||||
<div class="mt-4 grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3 gap-3 @md:gap-4">
|
||||
<div class="p-3 bg-gray-50 rounded">Stat 1</div>
|
||||
<div class="p-3 bg-gray-50 rounded">Stat 2</div>
|
||||
<div class="p-3 bg-gray-50 rounded">Stat 3</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Responsive Navigation
|
||||
|
||||
```html
|
||||
<div class="@container/nav">
|
||||
<nav class="flex flex-col @md/nav:flex-row @md/nav:items-center gap-2 @md/nav:gap-6">
|
||||
<a href="#" class="text-sm @md/nav:text-base">Home</a>
|
||||
<a href="#" class="text-sm @md/nav:text-base">About</a>
|
||||
<a href="#" class="text-sm @md/nav:text-base">Services</a>
|
||||
<a href="#" class="text-sm @md/nav:text-base">Contact</a>
|
||||
</nav>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Complex Layout Example
|
||||
|
||||
```html
|
||||
<div class="@container">
|
||||
<div class="grid grid-cols-1 @sm:grid-cols-2 @lg:grid-cols-3 @xl:grid-cols-4 gap-4 @md:gap-6 @lg:gap-8">
|
||||
<div class="@container/card">
|
||||
<article class="bg-white rounded-lg shadow-md overflow-hidden">
|
||||
<div class="relative h-32 @md/card:h-48 bg-gradient-to-br from-blue-500 to-purple-600">
|
||||
<img class="w-full h-full object-cover" src="/image.jpg" />
|
||||
</div>
|
||||
|
||||
<div class="p-3 @md/card:p-4 @lg/card:p-6">
|
||||
<h3 class="text-base @md/card:text-lg @lg/card:text-xl font-bold">
|
||||
Card Title
|
||||
</h3>
|
||||
|
||||
<p class="mt-2 text-xs @md/card:text-sm @lg/card:text-base text-gray-600 line-clamp-2 @lg/card:line-clamp-3">
|
||||
Description that adapts based on available space in the card container.
|
||||
</p>
|
||||
|
||||
<div class="mt-3 @md/card:mt-4 flex items-center justify-between">
|
||||
<span class="text-xs @md/card:text-sm text-gray-500">2 days ago</span>
|
||||
|
||||
<button class="px-2 py-1 @md/card:px-3 @md/card:py-1.5 text-xs @md/card:text-sm bg-blue-600 text-white rounded">
|
||||
Read
|
||||
</button>
|
||||
</div>
|
||||
</div>
|
||||
</article>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
## Mixing Container and Viewport Queries
|
||||
|
||||
You can combine both for maximum control:
|
||||
|
||||
```html
|
||||
<div class="@container">
|
||||
<div class="
|
||||
grid
|
||||
grid-cols-1
|
||||
md:grid-cols-2
|
||||
lg:grid-cols-3
|
||||
@lg:grid-cols-2
|
||||
@xl:grid-cols-3
|
||||
">
|
||||
Components adapt to both viewport and container
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
**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
|
||||
<div class="flex gap-6">
|
||||
<aside class="w-64 @container/sidebar">
|
||||
<nav class="space-y-2">
|
||||
<a class="block p-2 text-sm @md/sidebar:text-base">Link 1</a>
|
||||
<a class="block p-2 text-sm @md/sidebar:text-base">Link 2</a>
|
||||
</nav>
|
||||
</aside>
|
||||
|
||||
<main class="flex-1 @container/main">
|
||||
<div class="grid grid-cols-1 @lg/main:grid-cols-2 gap-4">
|
||||
<div>Content 1</div>
|
||||
<div>Content 2</div>
|
||||
</div>
|
||||
</main>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Product Grid
|
||||
|
||||
```html
|
||||
<div class="@container">
|
||||
<div class="grid grid-cols-2 @md:grid-cols-3 @lg:grid-cols-4 @xl:grid-cols-5 gap-4">
|
||||
<div class="@container/product">
|
||||
<div class="bg-white rounded-lg p-3 @md/product:p-4">
|
||||
<img class="w-full aspect-square rounded" src="/product.jpg" />
|
||||
<h3 class="mt-2 text-sm @md/product:text-base font-medium">Product</h3>
|
||||
<p class="mt-1 text-xs @md/product:text-sm text-gray-600">$99</p>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
</div>
|
||||
```
|
||||
|
||||
### Form Layout
|
||||
|
||||
```html
|
||||
<div class="@container">
|
||||
<form class="space-y-4 @md:space-y-6">
|
||||
<div class="grid grid-cols-1 @md:grid-cols-2 gap-4 @md:gap-6">
|
||||
<input class="px-3 py-2 @md:px-4 @md:py-3 border rounded" placeholder="First Name" />
|
||||
<input class="px-3 py-2 @md:px-4 @md:py-3 border rounded" placeholder="Last Name" />
|
||||
</div>
|
||||
|
||||
<button class="w-full px-4 py-2 @md:px-6 @md:py-3 bg-blue-600 text-white rounded">
|
||||
Submit
|
||||
</button>
|
||||
</form>
|
||||
</div>
|
||||
```
|
||||
|
||||
## See Also
|
||||
|
||||
- RESEARCH.md sections: "Container Queries" and "Usage Patterns"
|
||||
Reference in New Issue
Block a user