Web Components Community Group: 2021 Spec/API status

Form-associated custom elements allow custom elements to participate in forms to the same degree as native elements, including integrations with the form’s validation, state, and submission as well as exposing the Accessibility Object Model to the element.

A sample use case can be found in this article by Caleb Williams.

One of the most common use cases for web components is creating form controls not available natively. Some examples include switches and credit card inputs.

There is no way for forms to fully integrate with form elements located in a different shadow root the same way they would with form elements in the same root. The only options available to achieve a similar result are:

• The formdata event: this event only provides integration on form submission. Using this feature alone may also lead to accessibility issues due to the lack of cross-root ARIA.
• Setting a form element in light DOM (e.g. using slots): this gives web components authors two main options both of which will only work with standard form elements, mostly for form submission, and require both implementers and end users to write more code:
  • Visually hide the form element in light DOM and synchronize its value to a visible form element located inside the web component’s shadow root.
  • Have both the form element and its label located in slots and forgo the granular control shadow DOM gives you over how to allow for CSS customization.

This situation has forced developers to either not use web components for form elements or create their own form systems that allow for full integration (e.g. many big web component libraries such as Lion or Shoelace provide form systems that integrate with their components). This limits the reach web components could have as plug-in form elements for projects created with different tech stacks.

1. Shadow root encapsulation currently prevents references between elements in different roots. Cross-root ARIA references would re-enable this platform feature within shadow roots.
2. It's not possible to "forward" ARIA attributes from a custom element host into elements in the host's shadow root. For instance, a custom input that wants to allow users to customize the ARIA role, has no way to forward the role attribute to the encapsulated native input.

It's critically important that content on the web be accessible. Making web component content accessible currently requires many complicated and only partially-successful workarounds, such as:

• Observing and moving ARIA-related attributes across elements (for role, etc.)
• Using non-standard attributes for ARIA features, in order to apply them to elements in a shadow root.
• Requiring that custom elements users wrap/slot elements so that ARIA attributes can be placed directly on them. This gets very complicated as the number of slotted inputs and levels of shadow root nesting increase.
• Duplicating nodes across shadow root boundaries
• Abandoning Shadow DOM

Constructable Stylesheets and adoptedStyleSheets enable adding styles directly to shadow roots without creating new DOM elements. Because a single stylesheet object can be adopted by multiple scopes, it also allows sharing of styles that can be centrally modified.

• There is no effective way to share styles across components while allowing them to be centrally modified.
• Creating <style> elements for each style used in each shadow root has a measurable performance overhead.
• CSS Module Scripts, another critical feature, depends on constructible stylesheets.

CSS Module Scripts allow JavaScript modules to import style sheets. They can then be applied to a document or shadow root using adoptedStyleSheets in the same way as constructible style sheets.

import styleSheet from "./styles.css" assert { type: "css" };
document.adoptedStyleSheets = [ styleSheet ];

• CSS modules will allow styles to be loaded in component definitions without adding <style> or <link> elements that need to be created in each element instance.
• Authors today often use inlined CSS strings in JS modules, but many of them want to move the CSS into separate .css files.
• Without CSS-in-JS it's difficult to ensure that CSS is loaded before the component is defined and rendered. CSS module scripts provide the same ordering guarantee.
• Component authors may need to import a resource that is only available as an external .css file, and don't have control over the resource to wrap it in a JS module.

For further motivational details, see this explainer document: webcomponents/css-modules-v1-explainer.md at gh-pages · WICG/webcomponents.

Scoped element registries allow custom element definitions to be scoped to one or more shadow roots. This allows the same tag name to be used with different implementations in different parts of the page, greatly reducing tag name collisions.

There are a number of situations where multiple definitions of an element may be loaded into a page, leading to errors when the second definition executes:

• Unrelated name collisions: Unrelated web component libraries may attempt to register the same name; eg, <my-button>.
• Versioning: Often different versions of a library are required as dependencies of an application. If any library defines a custom element, only one version of that element can be registered. This can cause bugs with incompatible versions of the element being used.
• Distribution: Some elements are distributed via different channels, like CDNs and NPM. If a page consumes the library from multiple sources, that can lead to name collisions. The workarounds are not obvious.
• Encapsulation: Some components define and use other elements as internal implementation helpers. These elements should not have to be defined in a public global scope.

A partial polyfill for scoped custom element registries is available, but it has a number of drawbacks, including lower performance, and a requirement that all definitions have the same set of observed attributes.

Declarative Shadow DOM is a mechanism to express Shadow DOM using only HTML, with no dependency on JavaScript, much like light DOM can be declaratively expressed today.

For details, see this article by Jason Miller and Mason Freed.

Without Declarative Shadow DOM, web components depend on rendering environments that support JavaScript. This limits their use in:

• Server-Side Rendering: Without Declarative Shadow DOM, servers cannot deliver complete websites that include web component content. Markup cannot be efficiently delivered and then hydrated with JavaScript client-side.
• JavaScript-less environments: Many web components could be implemented without JavaScript, taking advantage of encapsulated DOM and styles. However, web components cannot currently be rendered by users who have JavaScript disabled. Developers who are more comfortable with markup than with scripting may avoid shadow DOM altogether due to its tight coupling with JavaScript.

Chrome has experimental support and a polyfill for Declarative Shadow DOM, but complete workarounds are not possible since Declarative Shadow DOM is a browser-level feature. Frameworks and libraries have hacked around this issue by prerendering sites, pages, or components in JavaScript-supporting environments prior to delivering HTML.

The ability to get a Selection from shadowRoot.getSelection() or document.getSelection(), then subsequently identify the selection range across composed trees of light and/or shadow DOM.

TPAC 18 resolved in consensus to add getComposedRange() to the existing Selection object (explainer). However, Selection.getComposedRange() is not yet implemented in any browser. Browsers also diverge in their implementations of shadowRoot.getSelection:

• Chrome always sets isCollapsed to true.
• Firefox has not implemented shadowRoot.getSelection, but returns shadow root anchorNodes from document.getSelection. This bug can be leveraged to polyfill shadowRoot.getSelection.
• Safari does not implement shadowRoot.getSelection and cannot be polyfilled.

Selection does not work consistently, or at all, across or within shadow roots. This makes fully-featured rich-text editors impossible to implement via web components. Some of the web’s most popular editors have issues that are blocked on this functionality:

• TinyMCE
• CKEditor
• Quill

Declarative shadow roots and constructible stylesheets need to be made to work together so that stylesheets added to shadow roots can be round-tripped through HTML serialization and deserialization.

Currently, there is no way to associate a declarative shadow root with a constructed stylesheet. This means that when a custom element with a shadow root and adopted stylesheets is serialized to HTML, it either loses its styling or some additional code has to convert the adopted stylesheets to style tags and insert them into the markup.

This is a proposal to add a new callback to the CEReaction extended attribute that would fire once an element's child has changed. This new callback would allow developers to deterministically know when child elements are added or removed, taking into account slotting.

• Simplicity: Currently, developers are using a combination of mutation observers and slotchange events to be notified when new elements have entered or removed from its scope. This would be replaced by a single callback function on the parent element.
• Children upgraded: When new children enter the parents scope there is no way of deterministically knowing that the child element has been upgraded with its custom element definition. Developers resort to polling, promise callbacks or timeouts to then wait for the child to finish upgrading before calling its APIs. The proposed callback would contain elements that have already been upgraded.

Open-styleable shadow roots would be a new mode on shadow roots that allow selectors from the shadow root's containing scope. This will allow component's internal DOM to be styled by page styles if there is a chain of open-styleable shadow roots up to the document scope - which in turn allow those components to be made to be compatible with existing pages so that projects can incrementally adopt shadow DOM.

Many potential consumers and providers of web components have raised the issue that they need to make components styleable with existing, and potentially unknown stylesheets. This is a common occurrence with systems like Bootstrap, Tailwind, or corporate stylesheets. The stylesheet may be loaded at the page level and maintained and distributed by a different team than the team building components. This scenario is extremely common for projects that are trying to port existing components to web components.

A common request for a solution to this problem is to be able to opt shadow roots into including styles from the scope above them. A chain of these "open-styleable" shadow roots from the top-level down would allow page styles to select against nodes in the shadow root.

While this does loosen encapsulation a lot, it also preserves many of the benefits of shadow DOM including upper bound style encapsulation, lower bound encapsulation to non-open-styleable shadow roots, DOM composition with slotting, and providing a scope for custom element registrations, ARIA/focus delegation, event composition, attaching constructible stylesheets and more.

We estimate this is a extremely large blocker to shadow DOM adoption. The inability to style shadow roots is one of the most common complaints on various GitHub/Twitter/Chat comments.

There is theoretically a workaround where a component reads styles from its containing scope and copies them into its own shadow root. This is difficult to make reactive to changes in DOM structure and new styles being added in parent scopes, and requires script so doesn't work with declarative shadow DOM.

ְDevelopers would like to define a custom element, it’s shadow-root, and styles from HTML, without need for JavaScript.

This would allow them to share reusable components easily without need for extra tooling, and to load them in <noscript> contexts. Declarative Shadow DOM allows developers to emulate this using build-tools, but requires repeating the declared shadow roots for each instance.

---

---