CSS Shadow Parts

1. Introduction

Shadow DOM allows authors to separate their page into "components", subtrees of markup whose details are only relevant to the component itself, not the outside page. This reduces the chance of a style meant for one part of the page accidentally over-applying and making a different part of the page look wrong. However, this styling barrier also makes it harder for a page to interact with its components when it actually wants to do so.

This specification defines the ::part() pseudo-element, which allows an author to style specific, purposely exposed elements in a shadow tree from the outside page’s context. In combination with custom properties, which let the outside page pass particular values (such as theme colors) into the component for it to do with as it will, these pseudo-elements allow components and the outside page to interact in safe, powerful ways, maintaining encapsulation without surrendering all control.

1.1. Motivation

For custom elements to be fully useful and as capable as built-in elements it should be possible for parts of them to be styled from outside. Exactly what can be styled from outside should be controlled by the element author. Also, it should be possible for a custom element to present a stable "API" for styling. That is, the selector used to style a part of a custom element should not expose or require knowledge of the internal details of the element. The custom element author should be able to change the internal details of the element while leaving the selectors untouched.

The previous proposed method for styling inside the shadow tree, the >>> combinator, turned out to be too powerful for its own good; it exposed too much of a component’s internal structure to scrutiny, defeating some of the encapsulation benefits that using Shadow DOM brings. For this, and other performance-related reasons, the >>> combinator was eventually removed from the live profile.

This left us with using custom properties as the only way to style into a shadow tree: the component would advertise that it uses certain custom properties to style its internals, and the outer page could then set those properties as it wished on the shadow host, letting inheritance push the values down to where they were needed. This works very well for many simple theming use-cases.

However, there are some cases where this falls down. If a component wishes to allow arbitrary styling of something in its shadow tree, the only way to do so is to define hundreds of custom properties (one per CSS property they wish to allow control of), which is obviously ridiculous for both usability and performance reasons. The situation is compounded if authors wish to style the component differently based on pseudo-classes like :hover; the component needs to duplicate the custom properties used for each pseudo-class (and each combination, like :hover:focus, resulting in a combinatorial explosion). This makes the usability and performance problems even worse.

We introduce ::part() to handle this case much more elegantly and performantly. Rather than bundling everything into custom property names, the functionality lives in selectors and style rule syntax, like it’s meant to. This is far more usable for both component authors and component users, should have much better performance, and allows for better encapsulation/API surface.

It’s important to note that ::part() offers absolutely zero new theoretical power. It is not a rehash of the >>> combinator, it is simply a more convenient and consistent syntax for something authors can already do with custom properties. By separating out the explicitly "published" parts of an element (the part element map) from the sub-parts that it merely happens to contain, it also helps with encapsulation, as authors can use ::part() without fear of accidental over-styling.

2. Exposing a Shadow Element:

Each element has a part name list which is an ordered set of tokens.

Each element has a forwarded part name list which is a list of pairs containing a string for the inner part being forwarded and a string giving the name it will be exposed as.

Each shadow root can be thought of as having a part element map with keys that are strings and values that are ordered sets of elements.

The part element map is described only as part of the algorithm for calculating style in this spec. It is not exposed via the DOM, as calculating it may be expensive and exposing it could allow access to elements inside closed shadow roots.

Part element maps are affected by the addition and removal of elements and changes to the part name lists and forwarded part name lists of elements in the DOM.

2.1. Naming a Shadow Element: the part attribute

Any element in a shadow tree can have a part attribute. This is used to expose the element outside of the shadow tree.

The part attribute is parsed as a space-separated list of tokens representing the part names of this element.

Note: It’s okay to give a part multiple names. The "part name" should be considered similar to a class, not an id or tagname.

<style>
  c-e::part(textspan) { color: red; }
</style>

<template id="c-e-template">
  <span part="textspan">This text will be red</span>
</template>
<c-e></c-e>
<script>
  // Add template as custom element c-e
  ...
</script>

2.2. Forwarding a Shadow Element: the exportparts attribute

The exportparts attribute is parsed as a comma-separated list of part mappings. Each part mapping is one of:

innerIdent : outerIdent

Adds innerIdent/outerIdent to el’s forwarded part name list.

ident

Adds ident/ident to el’s forwarded part name list.

Note: This is shorthand for ident : ident.

anything else

Ignored for error-recovery / future compatibility.

Note: It’s okay to map a sub-part to several names.

<style>
  c-e::part(textspan) { color: red; }
</style>

<template id="c-e-outer-template">
  <c-e-inner exportparts="innerspan: textspan"></c-e-inner>
</template>

<template id="c-e-inner-template">
  <span part="innerspan">
    This text will be red because the containing shadow
    host forwards innerspan to the document as "textspan"
    and the document style matches it.
  </span>
  <span part="textspan">
    This text will not be red because textspan in the document style
    cannot match against the part inside the inner custom element
    if it is not forwarded.
  </span>
</template>

<c-e></c-e>
<script>
  // Add template as custom elements c-e-inner, c-e-outer
    ...
</script>

3. Selecting a Shadow Element: the ::part() pseudo-element

The ::part() pseudo-element allows you to select elements that have been exposed via a part attribute. The syntax is:

::part() = ::part( <ident>+ )

The ::part() pseudo-element only matches anything when the originating element is a shadow host. If the originating element’s shadow root’s part element map contains all of the specified <ident>s, ::part() matches the element or elements keyed to that <ident>. Otherwise, it matches nothing.

The ::part() pseudo-element can take additional pseudo-classes after it, such as x-button::part(label):hover, but never matches the structural pseudo-classes or any other pseudo-classes that match based on tree information rather than local element information.

The ::part() pseudo-element can also take additional pseudo-elements after it, such as x-button::part(label)::before, but never match additional ::part()s.

4. Extensions to the Element Interface

partial interface Element {
  [SameObject, PutForwards=value] readonly attribute DOMTokenList part;
};

The part attribute’s getter must return a DOMTokenList object whose associated element is the context object and whose associated attribute’s local name is part. The token set of this particular DOMTokenList object are also known as the element’s parts.

Define this as a superglobal in the DOM spec. [Issue #w3c/csswg-drafts#3424]

5. Microsyntaxes for parsing

5.1. Rules for parsing part mappings

A valid part mapping is a pair of tokens separated by a U+003A COLON character and any number of space characters before or after the U+003A COLON The tokens must not contain U+003A COLON or U+002C COMMA characters.

The rules for parsing a part mapping are as follows:

1. Let input be the string being parsed.

2. Let position be a pointer into input, initially pointing at the start of the string.

3. Collect a sequence of code points that are space characters

4. Collect a sequence of code points that are not space characters or U+003A COLON characters, and let first token be the result.

5. If first token is empty then return error.

6. Collect a sequence of code points that are space characters.

7. If the end of the input has been reached, return the pair first token/first token

8. If character at position is not a U+003A COLON character, return error.

9. Consume the U+003A COLON character.

10. Collect a sequence of code points that are space characters.

11. Collect a sequence of code points that are not space characters or U+003A COLON characters. and let second token be the result.

12. If second token is empty then return error.

13. Collect a sequence of code points that are space characters.

14. If position is not past the end of input then return error.

15. Return the pair first token/second token.

5.2. Rules for parsing a list of part mappings

A valid list of part mappings is a number of valid part mappings separated by a U+002C COMMA character and any number of space characters before or after the U+002C COMMA

The rules for parsing a list of part mappings are as follow:

1. Let input be the string being parsed.

2. Split the string input on commas. Let unparsed mappings be the resulting list of strings.

3. Let mappings be an initially empty list of pairs of tokens. This list will be the result of this algorithm.

4. For each string unparsed mapping in unparsed mappings, run the following substeps:

   1. If unparsed mapping is empty or contains only space characters, continue to the next iteration of the loop.

   2. Let mapping be the result of parsing unparsed mapping using the rules for parsing part mappings.

   3. If mapping is an error then continue to the next iteration of the loop. This allows clients to skip over new syntax that is not understood.

   4. Append mapping to mappings.