Skip to content

ptcs-style-unit

Overview

The <ptcs-style-unit> injects CSS styling into the shadow DOM of Web Components, allowing it to style the internal elements.

This component runs in two modes: - Shadow DOM - For browsers that have native support for shadow DOM. - Shady DOM - For other browsers such as Edge. This mode has limitations that are discussed below.

The component detects the browser and sets the run mode automatically.

Usage Examples

Basic usage

Change the color of the radio button ring to red:

<ptcs-style-unit wc="PTCS-RADIO">
  [part=exterior-ring] {
    stroke: #FF0000;
  }
</ptcs-style-unit>

Styling a variant

Add a red border around the icon part in the primary ptcs-button's

<ptcs-style-unit wc="PTCS-BUTTON.primary">
  [part=icon] {
    border: 1px solid red;
  }
</ptcs-style-unit>

Styling sub-components

Style content in the clear-button part when it occurs in the date-field part in a ptcs-datepicker component:

<ptcs-style-unit wc="PTCS-DATEPICKER" part="date-field:clear-button">...</ptcs-style-unit>

The wc attribute always specifies the component where the styling starts. If any parts of the component is a sub-component, the part attribute allows you to drill down in that hierarchy and deliver the style into the correct shadow DOM.

Styling a specific component

Style content in a specific component:

<ptcs-style-unit wc="#my-button">...</ptcs-style-unit>

When the value of the wc attribute starts with #, it specifies the id of the targeted component. The styling is injected only into that component.

In Shady DOM mode, you should also specify the component name. Otherwise the ptcs-style-unit cannot prevent the styling from leaking into any sub-components.

Example:

<ptcs-style-unit wc="#my-button.ptcs-button">...</ptcs-style-unit>

Now the ptcs-style-unit knows that my-button is (supposed to be) a ptcs-button and can add the proper scoping rules.

If the browser runs in Shadow DOM mode it ignores this name.

Component API

Properties

Property Type Description Triggers a changed event?
part String The part to apply a style to. If you are apply styling to a part inside the target component, specify the part name using this property. If you are applying styles to a part within a part, then use ':' as a separator. If the part itself contains a part that should receive the styling, append that part name with a ':' as a separator. Repeat as long as needed. no
wc String Specifies the target component. You can specify the component by a name or by an id. Use uppercase letters when using a name. If the component specifies a variant attribute, the variant value should be concatenated with '.' as a separator. Make sure that character cases match. The component id is prefixed with #. You should concatenate the component name with '.' as a separator for compatibility with Shady DOM browsers. See above for examples. no

Methods

This component does not have any methods.

Styling

This component is not designed to be styled, and is hidden by default.

Notes about ptcs-style-unit styling

Web components hide their implementation. The component has a public interface and all interaction with the component should only use this interface. Writing code that is based on knowledge about the implementation details of a component is unsafe, since those details can change at any time. Only the public interface is stable and clearly documented.

When styling the internal structure of a web component, you should only use the public styling information. This information consists of:

  • any state attributes for the component.
  • the part names.
  • any state attributes for the parts.

The styling is not even supposed to know if certain parts contains other parts. This is consistent with the emerging W3C specification CSS Shadow Parts.

Adding any style sheet to the ptcs-style-unit in Shadow DOM mode is possible, but not recommended. In Shady DOM mode the styling must follow the styling rules, or the translation to shady DOM fails.

The styling rules applies to the CSS selectors. A CSS selector in a ptcs-style-unit should have this structure:

Selector structure in ptcs-style-unit

selector :- host part? | part

host     :- ':host' param?

param    :- '(' selector ')'

part     :- '[' 'part' is name] selector

is       :- '=' | '~=' | '|=' | '^='   note: use '~='

name     :- any valid part name

selector :- any valid CSS selector

Examples of valid ptcs-style-unit selectors

:host { ... }

:host([disabled]) { ... }

:host(:not([disabled]):hover) { ... }

[part~=label] { ... }

:host([variant=primary]) [part~=label]:not([disabled]):hover { ... }

Examples of invalid ptcs-style-unit selectors

img { ... }

.selected {...}

[disabled] [part=foo] .active

:host(:hover) #my-button {}

ptcs-style-context

Overview

The <ptcs-style-context> creates isolated compartment for <ptcs-style-unit> and <ptcs-state-unit> action.
<ptcs-style-unit> and <ptcs-state-unit> are affecting Web Components inside same <ptcs-style-context> compartment only, or whole document if no <ptcs-style-context> exist.

Native Shadow DOM is the only supported mode.

Usage Example

Use different styling for a part of the document - global and local buttons will have different styles

<ptcs-style-unit wc="PTCS-RADIO">
  [part=exterior-ring] {
    stroke: #FF0000;
  }
</ptcs-style-unit>
<ptcs-radio id="global"/>
<ptcs-style-context>
  <ptcs-style-unit wc="PTCS-RADIO">
    [part=exterior-ring] {
      stroke: #00FF00;
    }
  </ptcs-style-unit>
  <ptcs-radio id="local"/>
</ptcs-style-context>

Component API

Properties

Property Type Description
styleAggregator StyleAggregator StyleAggregator of the context (read only)

Methods

This component does not have any methods.

Styling

This component is not designed to be styled, and should be used with style="display:contents;"