revision:
- controls whether or not an element renders its contents at all, along with forcing a strong set of containments, allowing user agents to potentially omit large swathes of layout and rendering work until it becomes needed.
It enables the user agent to skip an element's rendering work (including layout and painting) until it is needed — which makes the initial page load much faster.
When to use: 1. long webpages with heavy off-screen content, 2. scollable lists/grids, 3. elements with frequent visibility toggles.
Property values:
visibile : no effect. The element's contents are laid out and rendered as normal.
auto : the element skips its contents. The skipped contents must not be accessible to user-agent features, such as find-in-page, tab-order navigation, etc., nor be selectable or focusable. This is similar to giving the contents "display: none".
hidden : the element turns on layout containment, style containment, and paint containment. If the element is not relevant to the user, it also skips its contents. Unlike hidden, the skipped contents must still be available as normal to user-agent features such as find-in-page, tab order navigation, etc., and must be focusable and selectable as normal.
Syntax examples
/* Keyword values */
content-visibility: visible;
content-visibility: hidden;
content-visibility: auto;
/* Global values */
content-visibility: inherit;
content-visibility: initial;
content-visibility: revert;
content-visibility: revert-layer;
content-visibility: unset;
Apply content-visibility: auto to sections that are initially off-screen (e.g., below the fold). This skips rendering until the user scrolls near the element.
example
<style>
.section {content-visibility: auto; /* Estimate height to prevent layout shifts */ contain-intrinsic-size: 500px; margin-bottom: 20px;}
</style>
<div class="section">Section 1 (Heavy Content)</div>
<div class="section">Section 2 (Heavy Content)</div>
Provide an estimated height/width to reserve space for off-screen elements, avoiding layout shifts when they render.
example
<style>
.section { content-visibility: auto; /* Syntax: contain-intrinsic-size: <width> <height>; */ contain-intrinsic-size: auto 500px; /* Auto width, 500px height */ }
</style>
For elements inside scrollable containers (e.g., a list), apply content-visibility: auto to individual items.
example
<style>
.scroll-container {height: 300px; overflow-y: auto;}
.item { content-visibility: auto; contain-intrinsic-size: 100px; padding: 12px;}
</style>
<div class="scroll-container">
<div class="item">Item 1</div>
<div class="item">Item 2</div>
<!-- 100+ items -->
</div>
Use content-visibility: hidden (instead of "display: none") for elements that toggle visibility, preserving rendering state.
example
<style>
.toggle-content {content-visibility: hidden; contain-intrinsic-size: 200px; /* Reserve space if needed */ }
</style>
<button onclick="toggle()">Show/Hide</button>
<div class="toggle-content" id="content">Hidden Content</div>
<script>
function toggle() {
const el = document.getElementById('content');
el.style.contentVisibility =
el.style.contentVisibility === 'hidden' ? 'visible' : 'hidden';
}
</script>
Supported browsers: Chromium (v85+), Firefox (v109+), Safari (partial).
Progressive enhancement: use @supports to avoid issues in unsupported browsers:
This content is initially hidden and can be shown by clicking the button.
This content is initially visible and can be hidden by clicking the button.
<div>
<div class="hidden">
<button class="toggle">Show</button>
<p> This content is initially hidden and can be shown by clicking the button.</p>
</div>
<div class="visible">
<button class="toggle">Hide</button>
<p>This content is initially visible and can be hidden by clicking the button.</p>
</div>
</div>
<style>
.hidden p, .visible p { contain-intrinsic-size: 0 1.1em; border: dotted 2px;}
.hidden > p {content-visibility: hidden;}
.visible > p {content-visibility: visible;}
</style>
<script>
const handleClick = (event) => {
const button = event.target;
const div = button.parentElement;
button.textContent = div.classList.contains("visible") ? "Show" : "Hide";
div.classList.toggle("hidden");
div.classList.toggle("visible");
};
document.querySelectorAll("button.toggle").forEach((button) => {
button.addEventListener("click", handleClick);
});
</script>
<div class="hidden1">
Hi, I'm hidden. Notice that all of my styling is hidden as well, and that
I still take up space, even though you can't see me.
<div class="visible1">
Howdy, my parent element is hidden, but I'm still visible. <br>Hover
over me to make my parent visible.
</div>
</div>
<style>
.hidden1 {visibility: hidden; background: pink; border: 10px dotted teal;
padding: 10px;
&:hover {visibility: visible;}
}
.visible1 {border: 1px solid black; visibility: visible;
}
</style>