The FCC just voted to kill net neutrality. Congress can still stop it.

CSS Shadow Parts

Editor’s Draft,

Specification Metadata
This version:
http://drafts.csswg.org/css-shadow-parts/
Issue Tracking:
Inline In Spec
GitHub Issues
Editors:
Tab Atkins-Bittner (Google)
(Google)
Suggest an Edit for this Spec:
https://github.com/w3c/csswg-drafts/blob/master/css-shadow-parts-1/Overview.bs

Abstract

This specification defines the ::part() and ::theme() pseudo-elements on shadow hosts, allowing shadow hosts to selectively expose chosen elements from their shadow tree to the outside page for styling purposes.

CSS is a language for describing the rendering of structured documents (such as HTML and XML) on screen, on paper, in speech, etc.

Status of this document

This is a public copy of the editors’ draft. It is provided for discussion only and may change at any moment. Its publication here does not imply endorsement of its contents by W3C. Don’t cite this document other than as work in progress.

GitHub Issues are preferred for discussion of this specification. When filing an issue, please put the text “css-shadow-parts” in the title, preferably like this: “[css-shadow-parts] …summary of comment…”. All issues and comments are archived, and there is also a historical archive.

This document was produced by the CSS Working Group (part of the Style Activity).

This document was produced by a group operating under the W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

This document is governed by the 1 February 2018 W3C Process Document.

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() and ::theme() pseudo-elements, which allow 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 surrending 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.

Another interesting facet of using custom properties, however, is that inheritance doesn’t stop at the first shadow tree. Unless explicitly blocked, a custom property inherits down thru nested trees, allowing authors to style deeply nested components as easily as they style directly-visible ones. The same considerations apply to this case, so we introduce ::theme() to handle this.

It’s important to note that ::part() and ::theme() offer absolutely zero new theoretical power. They are not a rehash of the >>> combinator, they’re 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 shadow part map from the sub-parts that it merely happens to contain (the computed shadow theme map, it also helps with encapsulation, as authors can use ::part() without fear of accidental over-styling.

2. Exposing a Shadow Element:

Elements in a shadow tree may be exposed for styling by stylesheets outside the tree using the part and partmap attributes.

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

Each element has a part name map which is an ordered map, with keys that are strings (part names to expose to selectors outside this element) and values that are ordered sets of strings (part names that are selectable inside this element).

Document how the part name map will be exposed via IDL. <https://github.com/w3c/csswg-drafts/issues/2414>

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 part name maps of elements in the DOM.

To calculate the part element map of a shadow root, outerRoot:

  1. For each element, el within outerRoot
    1. For each name in el’s part name list, add el to outerRoot’s part element map under the key name.
    2. If el is a shadow host itself then let innerRoot be its shadow root:
      1. Calculate innerRoot’s part element map.
      2. For each key, outerName, in el’s part name map and for each token innerName under that key look up innerName in innerRoot’s shadow part element map to get a (possibly empty) set of elements and add these elements to outerRoot’s part element map under outerName

There is no need for the part element map values to be ordered, can we drop that?

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 elment c-e
  ...
</script>

2.2. Forwarding a Shadow Element: the partmap attribute

Any element in a shadow tree can have a partmap attribute. If the element is a shadow host, this is used to allow styling of parts from hosts inside the shadow tree by rules outside this the shadow tree (as if they were elements in the same tree as the host, named by a part attribute).

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

innerIdent outerIdent

this adds «[ outerIdent → innerIdent ]» to el’s part name map.

ident

Is shorthand for ident ident.

anything else

Ignored for error-recovery / future compat.

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

Decide whether we use "inner outer" or "outer inner" <https://github.com/w3c/csswg-drafts/issues/2411>

Decide whether we use a separator between inner and outer idents. E.g. "inner => outer" or "inner : outer". <https://github.com/w3c/csswg-drafts/issues/2411>

Decide whether to allow "ident1 => ident2 ident3 ..." as shorthand for "ident1 ident2, ident1 ident3, ...". <https://github.com/w3c/csswg-drafts/issues/2411>

Decide whether to allow wild-card forwarding, e.g partmap="button-* buttons". Consider excluding sub-parts that have been explicitly forwarded. Consider a mechanism to exclude sub-parts without forwarding them. <https://github.com/w3c/csswg-drafts/issues/2411>

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

<template id="c-e-outer-template">
  <c-e-inner partmap="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 elments c-e-inner, c-e-outer
    ...
</script>

2.3. Exposing More Widely: the theme attribute

The theme section is intentionally a rough sketch at the moment. The functionality of theme can be achieved with part alone however it may be tedious to explicitly export parts as a theme. The need for theme will be better understood once part is in use.

In addition to the shadow part map, every shadow root has a partial shadow theme map and a computed shadow theme map both of which are ordered maps (with the same key/value shape as the shadow part map), and the elements in the shadow tree have a corresponding theme attribute.

The theme attribute is parsed and interpreted identically to the part attribute, except that it adds its entries to the shadow root’s partial shadow theme map instead.

If the shadow root’s mode is "closed", the computed shadow theme map is identical to the partial shadow theme map. Otherwise, it’s the union of the partial shadow theme map with the computed shadow theme maps of every shadow host’s shadow root in its shadow tree.

Decide if theme can ever/always penetrate closed shadow roots. <https://github.com/w3c/csswg-drafts/issues/2381>

3. Selecting a Shadow Element: the ::part() and ::theme() pseudo-elements

The ::part() and ::theme() pseudo-elements (collectively, the shadow-part pseudo-elements) allow you to select elements that have been exposed via a part attribute. The syntaxes of them are:

::part() = ::part( <ident> )
::theme() = ::theme( <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 the specified <ident>, ::part() matches the element or elements keyed to that <ident>. Otherwise, it matches nothing.

For example, if you have a custom button that contains a "label" element that is exposed for styling (via part="label"), you can select it with #the-button::part(label).

The ::theme() pseudo-element is similar, except it can match regardless of whether the originating element is a shadow host or not. It matches the elements keyed to the specified <ident> in the computed shadow theme map of the shadow trees of the originating element or any descendants.

For example, :root::theme(label) matches any element with part="label" anywhere in the entire document, no matter how deeply nested into shadow trees they are.

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

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

For example, x-panel::part(confirm-button)::part(label) never matches anything. This is because doing so would expose more structural information than is intended.

One can still target the nested label with a selector like x-panel::theme(label). However, this will also select the labels of any other buttons in the panel.

If the <x-panel>’s internal confirm button had used something like part="confirm-button, * => confirm-*" to forward the button’s internal parts up into the panel’s own part element map, then a selector like x-panel::part(confirm-label) would select just the one button’s label, ignoring any other labels.

Conformance

Document conventions

Conformance requirements are expressed with a combination of descriptive assertions and RFC 2119 terminology. The key words “MUST”, “MUST NOT”, “REQUIRED”, “SHALL”, “SHALL NOT”, “SHOULD”, “SHOULD NOT”, “RECOMMENDED”, “MAY”, and “OPTIONAL” in the normative parts of this document are to be interpreted as described in RFC 2119. However, for readability, these words do not appear in all uppercase letters in this specification.

All of the text of this specification is normative except sections explicitly marked as non-normative, examples, and notes. [RFC2119]

Examples in this specification are introduced with the words “for example” or are set apart from the normative text with class="example", like this:

This is an example of an informative example.

Informative notes begin with the word “Note” and are set apart from the normative text with class="note", like this:

Note, this is an informative note.

Advisements are normative sections styled to evoke special attention and are set apart from other normative text with <strong class="advisement">, like this: UAs MUST provide an accessible alternative.

Conformance classes

Conformance to this specification is defined for three conformance classes:

style sheet
A CSS style sheet.
renderer
A UA that interprets the semantics of a style sheet and renders documents that use them.
authoring tool
A UA that writes a style sheet.

A style sheet is conformant to this specification if all of its statements that use syntax defined in this module are valid according to the generic CSS grammar and the individual grammars of each feature defined in this module.

A renderer is conformant to this specification if, in addition to interpreting the style sheet as defined by the appropriate specifications, it supports all the features defined by this specification by parsing them correctly and rendering the document accordingly. However, the inability of a UA to correctly render a document due to limitations of the device does not make the UA non-conformant. (For example, a UA is not required to render color on a monochrome monitor.)

An authoring tool is conformant to this specification if it writes style sheets that are syntactically correct according to the generic CSS grammar and the individual grammars of each feature in this module, and meet all other conformance requirements of style sheets as described in this module.

Requirements for Responsible Implementation of CSS

The following sections define several conformance requirements for implementing CSS responsibly, in a way that promotes interoperability in the present and future.

Partial Implementations

So that authors can exploit the forward-compatible parsing rules to assign fallback values, CSS renderers must treat as invalid (and ignore as appropriate) any at-rules, properties, property values, keywords, and other syntactic constructs for which they have no usable level of support. In particular, user agents must not selectively ignore unsupported property values and honor supported values in a single multi-value property declaration: if any value is considered invalid (as unsupported values must be), CSS requires that the entire declaration be ignored.

Implementations of Unstable and Proprietary Features

To avoid clashes with future stable CSS features, the CSSWG recommends following best practices for the implementation of unstable features and proprietary extensions to CSS.

Implementations of CR-level Features

Once a specification reaches the Candidate Recommendation stage, implementers should release an unprefixed implementation of any CR-level feature they can demonstrate to be correctly implemented according to spec, and should avoid exposing a prefixed variant of that feature.

To establish and maintain the interoperability of CSS across implementations, the CSS Working Group requests that non-experimental CSS renderers submit an implementation report (and, if necessary, the testcases used for that implementation report) to the W3C before releasing an unprefixed implementation of any CSS features. Testcases submitted to W3C are subject to review and correction by the CSS Working Group.

Further information on submitting testcases and implementation reports can be found from on the CSS Working Group’s website at http://www.w3.org/Style/CSS/Test/. Questions should be directed to the public-css-testsuite@w3.org mailing list.

Index

Terms defined by this specification

Terms defined by reference

References

Normative References

[CSS-VALUES-4]
Tab Atkins Jr.; Elika Etemad. CSS Values and Units Module Level 4. 14 August 2018. WD. URL: https://www.w3.org/TR/css-values-4/
[CSS-VARIABLES-1]
Tab Atkins Jr.. CSS Custom Properties for Cascading Variables Module Level 1. 3 December 2015. CR. URL: https://www.w3.org/TR/css-variables-1/
[DOM]
Anne van Kesteren. DOM Standard. Living Standard. URL: https://dom.spec.whatwg.org/
[INFRA]
Anne van Kesteren; Domenic Denicola. Infra Standard. Living Standard. URL: https://infra.spec.whatwg.org/
[RFC2119]
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Best Current Practice. URL: https://tools.ietf.org/html/rfc2119
[SELECTORS-4]
Elika Etemad; Tab Atkins Jr.. Selectors Level 4. 2 February 2018. WD. URL: https://www.w3.org/TR/selectors-4/

Issues Index

Document how the part name map will be exposed via IDL. <https://github.com/w3c/csswg-drafts/issues/2414>
There is no need for the part element map values to be ordered, can we drop that?
Decide whether we use "inner outer" or "outer inner" <https://github.com/w3c/csswg-drafts/issues/2411>
Decide whether we use a separator between inner and outer idents. E.g. "inner => outer" or "inner : outer". <https://github.com/w3c/csswg-drafts/issues/2411>
Decide whether to allow "ident1 => ident2 ident3 ..." as shorthand for "ident1 ident2, ident1 ident3, ...". <https://github.com/w3c/csswg-drafts/issues/2411>
Decide whether to allow wild-card forwarding, e.g partmap="button-* buttons". Consider excluding sub-parts that have been explicitly forwarded. Consider a mechanism to exclude sub-parts without forwarding them. <https://github.com/w3c/csswg-drafts/issues/2411>
The theme section is intentionally a rough sketch at the moment. The functionality of theme can be achieved with part alone however it may be tedious to explicitly export parts as a theme. The need for theme will be better understood once part is in use.
Decide if theme can ever/always penetrate closed shadow roots. <https://github.com/w3c/csswg-drafts/issues/2381>