Skip to content
Tutorials Center
My learning

Topics

Lesson 109 of 139 ยท Modern CSS

@scope

Learn CSS @scope to limit styles to one part of a page, stop them at an inner boundary with donut scope, and let the nearest scope win conflicts.

Every CSS rule you write is global. A selector like .card img matches every image inside every card on the page, including images in a comment widget that happens to sit inside a card. Teams have fought this for years with naming conventions such as BEM, with tools that rename classes at build time, and with Shadow DOM.

The @scope at-rule gives you a native answer. It lets you say "these rules apply inside this element", and optionally "but stop here". It also adds a new step to the cascade, called scope proximity, so that when two scoped rules compete, the one whose scope is closer to the element wins. In this lesson you will learn all three ideas, plus how to ship @scope safely while support is still settling.

Support: @scope has worked in Chrome and Edge since 2023 and in Safari since 2024. Firefox was the last major engine to ship it, in late 2025. That means current browsers all understand it, but people on older versions do not. Browsers that don't recognize an at-rule skip the whole block, so the safe pattern is to write a plain fallback first and let @scope refine it. You will see exactly how at the end of this lesson.

Your first scoped rule

The prelude in parentheses names the scoping root. Rules inside the block only match elements inside that root:

CSS
@scope (.product) {
  img {
    border-radius: 8px;
  }

  :scope {
    padding: 1rem;
    border: 1px solid #ddd;
  }
}

Two things to notice:

  • img inside the block behaves like "an img that is a descendant of .product". You don't repeat .product in every selector.
  • :scope matches the root element itself, the .product. Use it whenever you want to style the container. (Inside @scope, & also refers to the root.)
Scoping rules to a component

If your browser supports @scope, only the card is styled. The heading below it is untouched, even though the scoped rules use plain h2 and p selectors.

Specificity inside @scope

Scoping does not add the root's specificity to the inner selectors. The h2 above still has the specificity of a type selector, (0,0,1), exactly as if it were global. That is a big difference from writing .product h2, which is (0,1,1). :scope counts like a pseudo-class, (0,1,0). Keeping specificity low makes components easy to override, which you learned about in Specificity.

Donut scope: setting a lower boundary

Components often contain other components. Picture a card that holds a user-written comment. You want the card's link styles, but not inside the comment, which has its own design. The to keyword sets a scoping limit:

CSS
@scope (.card) to (.comment) {
  a { color: darkgreen; }
}

Read it as "from .card down to, but not into, .comment". The limit element and everything inside it are excluded. The shape of the matched area, a ring with a hole in the middle, is why people call this donut scope.

Donut scope with to ()

The two links in the card turn bold and green. The "Reply" link inside .comment keeps the default style because it sits in the hole of the donut. Try deleting to (.comment) and run the example again: now all three links change.

The limit can be any selector, including a list. A common pattern stops a component at any nested component slot:

CSS
@scope (.tabs) to ([data-slot]) {
  /* styles for the tabs, never leaking into slotted content */
}

Scope proximity: the nearest scope wins

Here is the problem @scope solves that no naming convention can. Imagine light and dark themed regions that can nest inside each other:

CSS
.light a { color: navy; }
.dark a  { color: skyblue; }

Put a .dark panel inside a .light page, then a .light box inside that panel. A link in the innermost box should be navy. But both selectors have the same specificity, (0,1,1), so the later rule in the file wins and the link turns sky blue. The cascade knows nothing about which ancestor is closer.

With @scope, the cascade checks one more thing after specificity and before source order: how many generations separate the element from its scoping root. Fewer generations wins.

Proximity beats source order

The .dark block comes later in the file, so with ordinary descendant selectors it would win everywhere. With @scope, the innermost link is closer to its .light root than to the .dark root, so it stays navy. Swap the order of the two @scope blocks and nothing changes. That is proximity at work.

Remember where proximity sits in the cascade: after specificity. A more specific rule still wins regardless of distance. To learn the full order, revisit How the Cascade Works.

Inline scopes in a style element

You can also write @scope with no prelude inside a <style> element. The scoping root becomes the style element's parent:

HTML
<aside class="promo">
  <style>
    @scope {
      :scope { background: lemonchiffon; padding: 1rem; }
      strong { color: firebrick; }
    }
  </style>
  <p><strong>Free shipping</strong> on orders this weekend.</p>
</aside>

This keeps a small block of styles physically next to the markup it styles, which is handy for content from a CMS or for one-off widgets. Use it sparingly: styles scattered through the HTML are harder to find than styles in a stylesheet.

Shipping @scope with a fallback

Because a browser that doesn't understand @scope ignores the whole block, write the fallback first with ordinary selectors, then let a scoped block refine it. Unsupported browsers keep the fallback. Supporting browsers apply both, and the scoped rules can switch off anything that leaked.

You might reach for a feature query here. Testing an at-rule with @supports at-rule(@scope) is itself a very new feature, and browsers that don't understand that test treat the condition as false. So use it only to add extras, never to hold your only copy of important styles. In JavaScript, you can check for the CSSScopeRule interface.

Fallback first, then @scope

In a supporting browser, the card link is green and bold while the reply link inside the comment looks like normal text. In an older browser, both links are green: not perfect, but perfectly usable. The status line tells you which version you are seeing.

Look closely at the scoped selector. It is :scope a, not just a. A plain a inside @scope has specificity (0,0,1), which loses to the fallback .card a at (0,1,1), because specificity is checked before proximity. :scope a is (0,1,1) too, and it comes later in the file, so it wins. Change it to a plain a and run the example again to watch the fix stop working. @scope adds a step to the cascade; it does not override the others.

When to use @scope

@scope is a good fit when:

  • Components nest. Donut scope keeps a parent's styles out of child components.
  • Themes nest. Proximity makes the nearest theme win without specificity tricks.
  • You want short selectors. Plain h2 and img inside a scope stay low in specificity.

It is not a replacement for good organization. You still want clear component names, cascade layers for broad ordering, and nesting for states and variants. Layers decide which group of rules wins; @scope decides where a group applies. You will put these tools together in Organizing CSS.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. Inside @scope (.profile) { ... }, which selector targets the .profile element itself?

    :scope matches the scoping root. Plain selectors inside the block match descendants of the root.
  2. 2. What does @scope (.card) to (.comment) exclude?

    The to () limit sets the inner boundary. The limit element and its descendants are left out, creating a donut-shaped scope.
  3. 3. Two scoped rules have equal specificity. Which one wins?

    Scope proximity is checked after specificity and before source order, so the closer scope wins.
  4. 4. What specificity does img have inside @scope (.gallery) { img { } }?

    The scoping root does not add to the specificity of the selectors inside the block.
  5. 5. What is the safest way to use @scope for users with older browsers?

    Browsers that don't know @scope skip the block, so plain fallback rules keep the page working.

Summary

  • @scope (root) { } limits rules to elements inside the root. :scope targets the root itself.
  • @scope (root) to (limit) creates donut scope: the limit and its contents are excluded.
  • Scope proximity is a cascade step after specificity: the nearest scoping root wins ties.
  • Selectors inside @scope keep their own specificity; the root adds nothing.
  • @scope without a prelude inside a <style> element scopes to the style's parent.
  • Ship it with a plain fallback first, since older browsers ignore the whole block.

Next: Dark Mode, where you will build a theme that follows the user's system setting and still offers a manual switch.