CSS Nesting Module

1. Introduction

This section is not normative.

This module describes support for nesting a style rule within another style rule, allowing the inner rule’s selector to reference the elements matched by the outer rule. This feature allows related styles to be aggregated into a single structure within the CSS document, improving readability and maintainability.

1.1. Module Interactions

This module introduces new parser rules that extend the [CSS21] parser model. It introduces selectors that extend the [SELECTORS-4] module. It extends and modifies some IDL and algorithms defined in the [CSSOM-1] module.

1.2. Values

This specification does not define any new properties or values.

2. Explainer

This section is non-normative.

Imagine you have some CSS that you’d like to write in a more compact way.

.foo {
  color: green;
}
.foo .bar {
  font-size: 1.4rem;
}

With Nesting, you can write such code as:

.foo {
  color: green;
  .bar {
    font-size: 1.4rem;
  }
}

If you’ve been nesting styles in Sass or other CSS preprocessors, you will find this very familiar.

You can nest any rules inside of a parent style rule:

main {
  div { ... }
  .bar { ... }
  #baz { ...}
  :has(p) { ... }
  ::backdrop { ... }
  [lang|="zh"] { ... }
  * { ... }
}

By default, the child rule’s selector is assumed to connect to the parent rule by a descendant combinator, but you can start the nested selector with any combinator to change that:

main {
  + article { ... }
  > p { ... }
  ~ main { ... }
}

The new & selector lets you refer to the elements matched by the parent selector explictly, so the previous examples could have been written as:

main {
  & + article { ... }
  & > p { ... }
  & ~ main { ... }
}

But you can place the & in other locations within the nested selector, to indicate other types of relationships between the parent and child rule. For example, this CSS:

ul {
  padding-left: 1em;
}
.component ul {
  padding-left: 0;
}

Can be rewritten using Nesting as:

ul {
  padding-left: 1em;
  .component & {
    padding-left: 0;
  }
}

Again, the & gives you a way to say “this is where I want the nested selector to go”.

It’s also handy when you don’t want a space between your selectors. For example:

a {
  color: blue;
  &:hover {
    color: lightblue;
  }
}

Such code yields the same result as a:hover {. Without the &, you’d get a :hover {—​notice the space between a and :hover—​which would fail to style your hover link.

You can nest more than one layer deep—​nesting CSS inside already-nested CSS—​in as many levels as you desire. You can mix Nesting with Container Queries, Supports Queries, Media Queries, and/or Cascade Layers however you want. (Nearly) anything can go inside of anything.

3. Nesting Style Rules

Style rules can be nested inside of other styles rules. These nested style rules act exactly like ordinary style rules—​associating properties with elements via selectors—​but they "inherit" their parent rule’s selector context, allowing them to further build on the parent’s selector without having to repeat it, possibly multiple times.

A nested style rule is exactly like a normal style rule, except that it can use relative selectors, which are implicitly relative to the elements matched by the parent rule.

.foo {
  color: red;

  a {
    color: blue;
  }
}

.foo {
  color: red;
}
.foo a {
  color: blue;
}

.foo {
  color: red;

  &:hover {
    color: blue;
  }
}

/* equivalent to: */

.foo { color: red; }
.foo:hover { color: blue; }

.foo {
  color: red;

  + .bar {
    color: blue;
  }
}

/* equivalent to: */

.foo { color: red; }
.foo + .bar { color: blue; }

3.1. Syntax

The contents of style rules now accepts nested style rules and at-rules, in addition to the existing declarations.

Nested style rules differ from non-nested rules in the following ways:

• A nested style rule accepts a <relative-selector-list> as its prelude (rather than just a <selector-list>). Any relative selectors are relative to the elements represented by the nesting selector.

• If a selector in the <relative-selector-list> does not start with a combinator but does contain the nesting selector, it is interpreted as a non-relative selector.

The precise details of how nested style rules are parsed are defined in [CSS-SYNTAX-3].

An invalid nested style rule is ignored, along with its contents, but does not invalidate its parent rule.

Nested rules with relative selectors include the specificity of their implied nesting selector. For example, .foo { > .bar {...}} and .foo { & > .bar {...}} have the same specificity for their inner rule.

.foo {
  color: blue;
  &Bar { color: red; }
}
/* In Sass, this is equivalent to
  .foo { color: blue; }
  .fooBar { color: red; }
*/

If a <forgiving-selector-list> has an item that contains the nesting selector but is invalid, that item is preserved exactly as-is rather than being discarded. (This does not change the matching behavior of the selector—​an invalid selector still fails to match anything—​just the serialization of the selector.)

The preceding paragraph needs to move to Selectors when we move & itself to Selectors; I’m monkey-patching for convenience here.

3.2. Examples

/* & can be used on its own */
.foo {
  color: blue;
  & > .bar { color: red; }
  > .baz { color: green; }
}
/* equivalent to
  .foo { color: blue; }
  .foo > .bar { color: red; }
  .foo > .baz { color: green; }
*/


/* or in a compound selector,
   refining the parent’s selector */
.foo {
  color: blue;
  &.bar { color: red; }
}
/* equivalent to
  .foo { color: blue; }
  .foo.bar { color: red; }
*/

/* multiple selectors in the list are all
   relative to the parent */
.foo, .bar {
  color: blue;
  + .baz, &.qux { color: red; }
}
/* equivalent to
  .foo, .bar { color: blue; }
  :is(.foo, .bar) + .baz,
  :is(.foo, .bar).qux { color: red; }
*/

/* & can be used multiple times in a single selector */
.foo {
  color: blue;
  & .bar & .baz & .qux { color: red; }
}
/* equivalent to
  .foo { color: blue; }
  .foo .bar .foo .baz .foo .qux { color: red; }
*/

/* & doesn’t have to be at the beginning of the selector */

.foo {
  color: red;
  .parent & {
    color: blue;
  }
}
/* equivalent to
  .foo { color: red; }
  .parent .foo { color: blue; }
*/

.foo {
  color: red;
  :not(&) {
    color: blue;
  }
}
/* equivalent to
  .foo { color: red; }
  :not(.foo) { color: blue; }
*/

/* But if you use a relative selector,
  an initial & is implied automatically */

.foo {
  color: red;
  + .bar + & { color: blue; }
}

/* equivalent to
  .foo { color: red; }
  .foo + .bar + .foo { color: blue; }
*/

/* Somewhat silly, but & can be used all on its own, as well. */
.foo {
  color: blue;
  & { padding: 2ch; }
}
/* equivalent to
  .foo { color: blue; }
  .foo { padding: 2ch; }

  // or

  .foo {
    color: blue;
    padding: 2ch;
  }
*/

/* Again, silly, but can even be doubled up. */
.foo {
  color: blue;
  && { padding: 2ch; }
}
/* equivalent to
  .foo { color: blue; }
  .foo.foo { padding: 2ch; }
*/

/* The parent selector can be arbitrarily complicated */
.error, #404 {
  &:hover > .baz { color: red; }
}
/* equivalent to
  :is(.error, #404):hover > .baz { color: red; }
*/

.ancestor .el {
  .other-ancestor & { color: red; }
}
/* equivalent to
  .other-ancestor :is(.ancestor .el) { color: red; }

/* As can the nested selector */
.foo {
  & :is(.bar, &.baz) { color: red; }
}
/* equivalent to
  .foo :is(.bar, .foo.baz) { color: red; }
*/

/* Multiple levels of nesting "stack up" the selectors */
figure {
  margin: 0;

  > figcaption {
    background: hsl(0 0% 0% / 50%);

    > p {
      font-size: .9rem;
    }
  }
}
/* equivalent to
  figure { margin: 0; }
  figure > figcaption { background: hsl(0 0% 0% / 50%); }
  figure > figcaption > p { font-size: .9rem; }
*/

/* Example usage with Cascade Layers */
@layer base {
  html {
    block-size: 100%;

    body {
      min-block-size: 100%;
    }
  }
}
/* equivalent to
  @layer base {
    html { block-size: 100%; }
    html body { min-block-size: 100%; }
  }
*/

/* Example nesting Cascade Layers */
@layer base {
  html {
    block-size: 100%;

    @layer support {
      body {
        min-block-size: 100%;
      }
    }
  }
}
/* equivalent to
  @layer base {
    html { block-size: 100%; }
  }
  @layer base.support {
    html body { min-block-size: 100%; }
  }
*/

/* Example usage with Scoping */
@scope (.card) to (> header) {
  :scope {
    inline-size: 40ch;
    aspect-ratio: 3/4;

    > header {
      border-block-end: 1px solid white;
    }
  }
}
/* equivalent to
  @scope (.card) to (> header) {
    :scope { inline-size: 40ch; aspect-ratio: 3/4; }
    :scope > header { border-block-end: 1px solid white; }
  }
*/

/* Example nesting Scoping */
.card {
  inline-size: 40ch;
  aspect-ratio: 3/4;

  @scope (&) to (> header > *) {
    :scope > header {
      border-block-end: 1px solid white;
    }
  }
}

/* equivalent to
  .card { inline-size: 40ch; aspect-ratio: 3/4; }
  @scope (.card) to (> header > *) {
    :scope > header { border-block-end: 1px solid white; }
  }
*/

3.3. Nesting Other At-Rules

In addition to nested style rules, this specification allows nested group rules inside of style rules: any at-rule whose body contains style rules can be nested inside of a style rule as well.

When nested in this way, the contents of a nested group rule's block are parsed as <block-contents> rather than <rule-list>:

• Style rules are nested style rules, with their nesting selector taking its definition from the nearest ancestor style rule.

• Properties can be directly used, acting as if they were nested in a nested declarations rule.

The meanings and behavior of such nested group rules is otherwise unchanged, unless otherwise specified.

/* Properties can be directly used */
.foo {
  display: grid;

  @media (orientation: landscape) {
    grid-auto-flow: column;
  }
}

/* equivalent to: */
.foo {
  display: grid;
}
@media (orientation: landscape) {
  .foo {
    grid-auto-flow: column
  }
}

/* and also equivalent to the unnested: */
.foo { display: grid; }

@media (orientation: landscape) {
  .foo {
    grid-auto-flow: column;
  }
}

/* Conditionals can be further nested */
.foo {
  display: grid;

  @media (orientation: landscape) {
    grid-auto-flow: column;

    @media (min-width > 1024px) {
      max-inline-size: 1024px;
    }
  }
}

/* equivalent to */
.foo { display: grid; }

@media (orientation: landscape) {
  .foo {
    grid-auto-flow: column;
  }
}

@media (orientation: landscape) and (min-width > 1024px) {
  .foo {
    max-inline-size: 1024px;
  }
}

/* Example nesting Cascade Layers */
html {
  @layer base {
    block-size: 100%;

    @layer support {
      & body {
        min-block-size: 100%;
      }
    }
  }
}

/* equivalent to */
@layer base {
  html { block-size: 100%; }
}
@layer base.support {
  html body { min-block-size: 100%; }
}

/* Example nesting Scoping */
.card {
  inline-size: 40ch;
  aspect-ratio: 3/4;

  @scope (&) {
    :scope {
      border: 1px solid white;
    }
  }
}

/* equivalent to */
.card { inline-size: 40ch; aspect-ratio: 3/4; }
@scope (.card) {
  :scope { border-block-end: 1px solid white; }
}

Runs of consecutive directly-nested properties are automatically wrapped in nested declarations rules. (This is observable in the CSSOM.)

3.3.1. Nested @scope Rules

When the @scope rule is a nested group rule, an & in the <scope-start> selector refers to the elements matched by the nearest ancestor style rule.

For the purposes of the style rules in its body and its own <scope-end> selector, the @scope rule is treated as an ancestor style rule, matching the elements matched by its <scope-start> selector.

.parent {
  color: blue;

  @scope (& > .scope) to (& .limit) {
    & .content {
      color: red;
    }
  }
}

.parent { color: blue; }
@scope (.parent > .scope) to (.parent > .scope .limit) {
  .parent > .scope .content {
    color: red;
  }
}

3.4. Mixing Nesting Rules and Declarations

When a style rule contains both declarations and nested style rules or nested group rules, all three can be arbitrarily mixed. Declarations coming after or between rules are implicitly wrapped in nested declarations rules, to preserve their order relative to the other rules.

article {
  color: green;
  & { color: blue; }
  color: red;
}

/* equivalent to */
article { color: green; }
:is(article) { color: blue; }
article { color: red; }

/* NOT equivalent to */
article { color: green; }
article { color: red; }
:is(article) { color: blue; }

For the purpose of determining the Order Of Appearance, nested style rules and nested group rules are considered to come after their parent rule.

article {
  color: blue;
  & { color: red; }
}

article {
  color: blue;
  :where(&) { color: red; }
}

Note: While one can freely intermix declarations and nested rules, it’s harder to read and somewhat confusing to do so, since the later properties are automatically wrapped in a nested declarations rule that doesn’t appear in the source text. For readability’s sake, it’s recommended that authors put all their properties first in a style rule, before any nested rules. (This also happens to act slightly better in older user agents: due to specifics of how parsing and error-recovery work, properties appearing after nested rules can get skipped.)

4. Nesting Selector: the & selector

When using a nested style rule, one must be able to refer to the elements matched by the parent rule; that is, after all, the entire point of nesting. To accomplish that, this specification defines a new selector, the nesting selector, written as & (U+0026 AMPERSAND).

When used in the selector of a nested style rule, the nesting selector represents the elements matched by the parent rule. When used in any other context, it represents the same elements as :scope in that context (unless otherwise defined).

a, b {
  & c { color: blue; }
}

:is(a, b) c { color: blue; }

The nesting selector cannot represent pseudo-elements (identical to the behavior of the :is() pseudo-class).

.foo, .foo::before, .foo::after {
  color: red;

  &:hover { color: blue; }
}

.foo, .foo::before, .foo::after {
  color: red;
}
.foo:hover {
  color: blue;
}

We’d like to relax this restriction, but need to do so simultaneously for both :is() and &, since they’re intentionally built on the same underlying mechanisms. (Issue 7433)

The specificity of the nesting selector is equal to the largest specificity among the complex selectors in the parent style rule’s selector list (identical to the behavior of :is()), or zero if no such selector list exists.

#a, b {
  & c { color: blue; }
}
.foo c { color: red; }

<b class=foo>
  <c>Blue text</c>
</b>

.a1, .a2, .a3 {
  .b1, .b2, .b3 {
    .c1, .c2, .c3 {
      ...;
    }
  }
}

/* naively desugars to */
.a1 .b1 .c1,
.a1 .b1 .c2,
.a1 .b1 .c3,
.a1 .b2 .c1,
.a1 .b2 .c2,
.a1 .b2 .c3,
.a1 .b3 .c1,
.a1 .b3 .c2,
.a1 .b3 .c3,
.a2 .b1 .c1,
.a2 .b1 .c2,
.a2 .b1 .c3,
.a2 .b2 .c1,
.a2 .b2 .c2,
.a2 .b2 .c3,
.a2 .b3 .c1,
.a2 .b3 .c2,
.a2 .b3 .c3,
.a3 .b1 .c1,
.a3 .b1 .c2,
.a3 .b1 .c3,
.a3 .b2 .c1,
.a3 .b2 .c2,
.a3 .b2 .c3,
.a3 .b3 .c1,
.a3 .b3 .c2,
.a3 .b3 .c3 {...}

The nesting selector is capable of matching featureless elements, if they were matched by the parent rule.

While the position of a nesting selector in a compound selector does not make a difference in its behavior (that is, &.foo and .foo& match the same elements), the existing rule that a type selector, if present, must be first in the compound selector continues to apply (that is, &div is illegal, and must be written div& instead).

5. The Nested Declarations Rule

For somewhat-technical reasons, it’s important to be able to distinguish properties that appear at the start of a style rule’s contents from those that appear interspersed with other rules.

.foo {
  color: red;
  @media (...) {...}
  background: blue;
}

To accomplish this, CSS parsing automatically wraps such properties in a special child rule to contain them. However, if we were to wrap them in a style rule with an & selector, it would have somewhat unfortunate behavior:

.foo, .foo::before {
  color: red;
  & {
    background: blue;
  }
}

Similarly, child declarations in nested non-style rules need to be exposed as rules in some way, because these sorts of rules (like @media) have never had style properties. These run into the same problems as above.

To address all of these issue, we instead wrap runs of consecutive directly-nested properties in a nested declarations rule.

Unless otherwise specified, a nested declarations rule is a nested style rule, and acts identically to any other style rule. It matches the exact same elements and pseudo-elements as its parent style rule, with the same specificity behavior. (This is similar to being a style rule with an & selector, but slightly more powerful, as explained above.)

.foo, .foo::before, .foo::after {
  color: black;
  @media (prefers-color-scheme: dark) {
    & {
      color: white;
    }
  }
}

.foo, .foo::before, .foo::after {
  color: black;
  @media (prefers-color-scheme: dark) {
    color: white;
  }
}

.foo {
  color: black;
  @media (...) {...}
  background: silver;
}

6. CSSOM

Note: [CSSOM-1] now defines that CSSStyleRule can have child rules.

When serializing a relative selector in a nested style rule, the selector must be absolutized, with the implied nesting selector inserted.

6.1. The CSSNestedDeclarations Interface

The CSSNestedDeclarations interface represents a nested declarations rule.

[Exposed=Window]
interface CSSNestedDeclarations : CSSRule {
  [SameObject, PutForwards=cssText] readonly attribute CSSStyleProperties style;
};

The CSSNestedDeclarations rule serializes as if its declaration block had been serialized directly.

Note: This means that multiple adjacent nested declarations rules (which is possible to create with e.g. insertRule) will collapse into a single rule when serialized and parsed again.

7. Changes

Significant changes since the Feb 14, 2023 Working Draft:

• Clarified that the nesting selector is allowed to match featureless elements.

• Switched &div back to being invalid; now that Syntax does "infinite lookahead", we no longer need to allow it. Plus, doing so avoids a clash with preprocessors. (Issue 8662)

• CSSOM now defines that CSSStyleRule is a CSSGroupingRule subclass, so the manual definition of the cssRules attribute and related machinery was removed. (Issue 8940)

• Clarified the effect of the implied nesting selector on specificity. (Issue 9069)

• Declarations intermixed with rules (or all declarations in nested group rules) are now automatically wrapped in @nest rules. (Also the @nest rule was added.) (Issue 8738)

• Replaced @nest with nested declarations rules. (Issue 10234)