Shadow DOM v0 and HTML imports are changing

In the near future, Chrome is rolling out two changes that may affect existing Polymer 1.x and 2.x websites:

Shadow-piercing selectors will be disabled. Chrome 63 will disable the shadow-piercing selectors (/deep/ and ::shadow) in style sheets. This change only affects sites using Polymer 1.x that are using native shadow DOM.

HTML imports will no longer automatically style the main document. Chrome 65 will make a change to the behavior of HTML imports. Currently, styles from an HTML import are automatically applied to the main document. This behavior is going away in Chrome 65. This change affects sites using either Polymer 1.x or Polymer 2.x.

Shadow-piercing selectors

The /deep/ combinator acts like the descendant combinator (in other words html /deep/ div is treated the same as html div). This prevents some global style sheets from breaking entirely.

The ::shadow pseudo class selector doesn't match any elements.

Note /deep/ and ::shadow still function when used from JavaScript APIs like querySelector and querySelectorAll.

We first posted about moving away from /deep/ in December 2015, so hopefully this is not news to most people. This change only affects Polymer 1.x and web components v0; the web components v1 specs used in Polymer 2.x don't support /deep/ or ::shadowat all.

This change is already in Chrome Canary, and will roll out to the stable channel at the beginning of December. Now is the time to test your sites and make sure that they work in Canary.

Because they don't use shadow-piercing selectors, you need to import these modules into each scope where they're used—that is, into each element that uses the layout classes, and also at the document level if you use layout classes there.

Using shady DOM

If you still have /deep/ styles that you can't work around, you can work around the issue by using shady DOM instead of native shadow DOM. Using shady DOM everywhere is the default setting for Polymer 1.x, so you're only using native shadow DOM if you explicitly enabled it. Reverting to shady DOM will hurt performance on Chrome, so you should regard this as a last resort.

If you're not sure whether you're using native shadow DOM, check for a settings script like this:

The settings script is usually in your entrypoint, since it needs to run before you load Polymer or any Polymer element definitions.

If you have a script block like this, you can comment out the dom: 'shadow' line, or remove the script entirely (if that's the only setting you currently use).

If you don't have a script block like this in your entrypoint, you're already using shady DOM.

HTML imports styling the main document

In current versions of Chrome, any <style> elements in an HTML import affect the main document. For Polymer users, this usually means components like paper-styles, which set custom properties using a custom style element (<custom-style> in Polymer 2.x, <style is="custom-style"> in Polymer 1.x). This change doesn't affect styles defined inside a <template>, such as the shadow DOM template for a Polymer element. But it may affect files that you use to define themes:

If you are using any HTML imports like this, you'll see a deprecation warning in the Chrome console:

[Deprecation] Styling master document from stylesheets defined in HTML Imports isdeprecated, andis planned to be removed in M65, around March 2018. Please refer to https://goo.gl/EGXzpw for possible migration paths.

The good news is we already have a fix for this in the latest versions of Polymer 1.x and 2.x. The bad news is that we can't make the warning go away. (We're looking into a workaround to suppress this warning, which could be shipped in a subsequent version of Polymer.)

With the fix, the custom-style element moves its styles into the main document. Unfortunately, the custom style element can't do that until after the browser has parsed the HTML import and printed the warning. So you'll continue to see the warning after upgrading.

What you should do in the next month or two:

Ensure that you're running the latest 1.x or 2.x release (1.10.1 or newer for 1.x; 2.1.1 or newer for 2.x).

If you have any HTML imports that contain ordinary style tags—not wrapped in a custom-style element or inside a template—use a custom-style element instead, to ensure the styles are moved into the main document.