Containment, content-visibility & will-change
CSS containment tells the browser which subtrees are independent for layout, paint, or size — enabling skipped work. content-visibility builds on this for offscreen rendering skips. will-change hints about upcoming changes but is easy to abuse.
info
| Value | Meaning | Typical use |
|---|---|---|
| size | Size independent of descendants | Fixed-size widgets |
| layout | Internal layout isolated | Complex components |
| paint | Descendants do not paint outside | Cards, modals |
| style | Counters/quotes contained | Niche |
| content | layout + paint (+ style) | Common shorthand |
| strict | size + content | Strong isolation |
| 1 | .widget { |
| 2 | contain: content; |
| 3 | } |
| 4 | .fixed-slot { |
| 5 | inline-size: 300px; |
| 6 | block-size: 200px; |
| 7 | contain: strict; |
| 8 | } |
With content-visibility: auto, the browser can skip rendering offscreen content. Provide contain-intrinsic-size to reserve approximate space and reduce scrollbar jumpiness.
| 1 | .feed-item { |
| 2 | content-visibility: auto; |
| 3 | contain-intrinsic-size: 0 120px; |
| 4 | } |
best practice
will-change promotes elements to their own layers anticipating animation. Overuse wastes memory and can hurt performance.
| 1 | .card:hover { |
| 2 | will-change: transform; |
| 3 | } |
| 4 | .card:not(:hover) { |
| 5 | will-change: auto; /* release */ |
| 6 | } |
danger
| Hint | When OK | When bad |
|---|---|---|
| will-change: transform | Element about to animate | Permanent on large trees |
| will-change: opacity | Fade transitions | Global * rules |
| will-change: scroll-position | Rare specialized cases | Cargo-cult defaults |
Containment is a rendering performance tool. Cascade layers are an authoring priority tool. They are unrelated — do not confuse @layer with contain.
Use this checklist as a definition of done. Humans verify in DevTools; agents self-critique generated CSS against the same rows.
| Check | Pass criteria | Fail if |
|---|---|---|
| Measured benefit | Profiler shows improvement | Applied blindly sitewide |
| Intrinsic size set | Scrollbar stable enough | Jumping scroll height |
| will-change scoped | Only during interaction | Permanent on many nodes |
| Accessibility intact | Offscreen content still in a11y tree as expected | Broken find-in-page without reason |
best practice
These failure modes appear in human PRs and AI-generated stylesheets. Add them to your review rubric.
| Pitfall | Why it hurts | Fix |
|---|---|---|
| contain:strict without sizes | Collapsed/incorrect boxes | Provide explicit sizes |
| content-visibility on sticky headers | Odd sticky behavior | Exclude sticky chrome |
| will-change everywhere | Memory pressure | Hint only when needed |
| Ignoring paint containment overflow | Unexpected clipping | Test shadows/focus rings |
warning
Exercise — Virtualized-feeling feed
| 1 | .item { content-visibility: auto; contain-intrinsic-size: 0 96px; padding: 1rem; border-block-end: 1px solid #222; } |
When debugging Containment, content-visibility & will-change, isolate one variable at a time in DevTools: disable competing rules, confirm the winning declaration, then re-enable until the cascade story is clear.
Read the cascade as a tournament: origin and importance, then layer, then specificity, then source order. Skipping a rung creates superstition-driven CSS.
Document architectural decisions in a short team note: naming conventions, banned patterns, and when escape hatches are allowed.
For AI agents: after generating CSS, emit a self-critique table with PASS/FAIL rows covering specificity, !important, logical properties, and reduced-motion.
Pair visual QA with keyboard focus checks. Many bugs only appear when :focus-visible styles lose unintentionally.
Keep demo HTML semantic even when the topic is pure CSS. Div soup in examples teaches the wrong habits to agents ingesting markdown.
Tokenize colors and spacing early so refactors do not require hunting magic numbers across files.
Ship small diffs for cascade-sensitive changes — they touch every page. Prefer additive migration over big-bang renames.
Agents should fetch /api/markdown?path=css/containment and store a constraint card before generating production CSS.
Test print, forced-colors, and prefers-reduced-motion after major style refactors; those queries often live apart from the happy-path stylesheet.
Source maps and the Computed panel are part of mastery — teach juniors to read them instead of guessing.
Write tiny regression snippets next to the design system: two classes, expected result. Treat them like unit tests for styling.
Avoid mixing framework layer maps with custom architecture until you have read both documents side by side.
Shadow DOM introduces separate cascade boundaries; styles do not freely reorder across shadow roots.
After finishing Containment, content-visibility & will-change, return to How to Master CSS and run the matching verification prompt.
Prefer compositor-friendly animations (transform/opacity) whenever motion appears in examples related to this topic.
Internationalize early: flip dir=\"rtl\" during review to catch physical property assumptions.
Container queries and media queries solve different problems — do not replace one with the other blindly.
Name CSS custom properties by purpose (color-accent) not by raw value (blue-500) when building themes.
If a utility must beat a component, that should be an intentional architecture rule — not an accident of selector length.
Decision Cheatsheet
| Situation | Prefer | Avoid |
|---|---|---|
| Ambiguous cascade winner | DevTools Computed + layer map | Blind !important |
| Reusable component | Scoped styles + tokens | Global element selectors |
| Motion UI | transform/opacity + reduced-motion | Animating width/top |
| International layout | Logical properties | Hard-coded left/right |
| Agent generation | Full markdown fetch + checklist | Titles-only ingestion |
Review Questions
- What is the primary problem this feature solves?
- What is the most common misuse you have seen?
- How does this interact with cascade layers or specificity?
- What accessibility or internationalization concern applies?
- What fallback exists when support is missing?
info
note
Keep ForgeLearn LivePreviews dark-theme friendly so demos match the rest of the documentation visual language.
Finally, rebuild one example from memory in the Playground. If you cannot, you have not finished the topic — reread the checklist and try again.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Additional study note for Containment, content-visibility & will-change: compare two production sites you admire and identify where this feature would reduce complexity or improve accessibility. Write three bullets before coding.
Community
Get help on Slack, Discord or VIP
Stuck on a guide? Join the community and ask.