Skip to main content

CSS Shadow Parts

CSS Shadow Parts - Customize the styles of elements inside the Shadow DOM.

CSS Shadow Parts is a feature that allows developers to style specific parts of the Shadow DOM . This is useful in the case of WebJET Elements built on Web Components technology, where encapsulation would otherwise not allow the appearance of the internal parts of the elements to be modified.

Benefits of Shadow parts​

Shadow Parts provide a way to expose specific elements within the Shadow DOM for styling purposes, while maintaining its benefits of encapsulation and isolation according to the Shadow DOM specification. This avoids the risk of styles being transferred from components and inadvertently applied to other elements.

Using Shadow parts​

When using Web components with Shadow DOM, it is not possible to target the internals of the component using the CSS selector. As we explained above, everything inside the Shadow DOM is isolated from the rest of the application. The example below shows how the wj-select component is rendered.

<wj-button>
  #shadow-root
  <button class="button-native" part="native"></button>
</wj-button>

The element button inside #shadow-root is encapsulated and therefore the CSS selector below will not work.

/* Non-functional selector */
wj-button .button-native {
  color: blue;
}

This problem is solved by CSS Shadow Parts. The wj-button component contains a part attribute with a value that can be targeted in css using the css pseudo-element::part(). In this case it is the value native.

A functional css selector would therefore look like this:

wj-button::part(native) {
  color: blue;
}

More information on how

How ::part works​

The ::part() pseudo-element allows developers to select elements inside of a shadow tree that have been exposed via a part attribute.

Since we know that ion-select exposes a placeholder part for styling the text when there is no value selected, we can customize it in the following way:

ion-select::part(placeholder) {
  color: blue;
  opacity: 1;
}

Styling with ::part allows you to change any CSS property that the element accepts.

WebJET Elements parts​

All exposed parts for an Ionic Framework component can be found under the CSS Shadow Parts heading on its API page. To view all components and their API pages, see the Component documentation.

Limitations​

Compatibility with browsers​

Shadow Parts CSS works in the latest versions of all major browsers. However, older browser versions may not support them. Before using Shadow Parts in your application, check browser compatibility to make sure it fits your requirements. If you need to support older browsers, consider CSS Variables instead for editing styles.

Support for browser-prefixed pseudoelements​

Vendor-prefixed

pseudo-elements are not currently supported. Therefore, for example, the ::-webkit-scrollbar pseudoelement in the example below will not work.

/* Not supported */
my-component::part(scroll)::-webkit-scrollbar {
  background: green;
}

See this issue on GitHub for more information.

Structural pseudo-classes​

Most pseudo-classes are supported using parts, but structural pseudo-classes are not supported. An example of structural pseudo-classes that do not work is given below.

/* Not supported */
my-component::part(container):first-child {
  background: green;
}

/* Not supported */
my-component::part(container):last-child {
  background: green;
}

Chaining multiple Parts​

The ::part() pseudoelement cannot chain multiple ::part() selectors. This is to avoid exposing redundant component content. If you need to target a specific part, use the value of that part directly.

/* Not supported */
my-component::part(button)::part(label)

Content