Style

The Style CPart allows us to write CSS for our component. This allows us to group styles within our component, and keep them isolated from other components, without having to come up with long, confusing class names every time. CSS written here will be automatically prefixed so that it will only apply to your component and/or any HTML that it generates, such as by the Template CPart.

General usage

In general, you can freely write any number of CSS rules for your components. They will be prefixed based on a few regular expression replacement steps, such that they only apply to the elements within your component. For example, a rule like a { color: blue } in a component named name="HelloBtn" that has been imported with namespace="mylib" would result in the following, fully-prefixed rule: mylib-HelloBtn a { color: blue }

Typical usage

<Template>
Hello <strong>Modulo</strong> World!
<p class="neat">Any HTML can be here!</p>
</Template>
<Style>
/* ...and any CSS here! */
strong {
    color: blue;
}
.neat {
    font-variant: small-caps;
}
:host { /* styles the entire component */
    display: inline-block;
    background-color: cornsilk;
    padding: 5px;
    box-shadow: 10px 10px 0 0 turquoise;
}
</Style>

Advanced usage

If you want to go deeper, you might customize it with specifying a url-replace mode, or an isolation-mode.

URL Replacement

By default (url-replace:=true), it will attempt to "fix" all relative URLs into absolute URLs, either with the host specified or without, if (and only if) you imported that Style with a -src= attribute. To turn off this feature, specify url-replace:=false on your Style component.

URL replacement example

To see the url-replace feature in action, see below:

<Template>
    Hello <strong>Modulo</strong> World! <p class="neat">This
    background works even when the CSS is bundled.</p>
</Template>
<!-- In sample.css, we have background: url('./example_image.jpg')
    and its replaced with url('/static/data/eg/example_image.jpg') -->
<Style
    -src="/static/data/eg/sample.css"
></Style>

Without url-replace

To see why it's necessary, try disabling the url-replace feature and note how the background no longer works (since it will use the relative URL given in the image, which is then relative to this page, instead of the CSS file):

Isolation modes

The Style CPart is capable of "isolating" it's contents using one of several strategies: Prefix isolation (using the "descendent" CSS selector), Class isolation (where a class is attached to all matching elements generated by the Component, and the :is() CSS selector is used to join the class with all selectors in the Component), and finally Shadow

Prefix isolation (default for `<Component ...`)

By default, components have "regular" rendering mode. This will cause it to prefix like described above. That is, every selector in the CSS styles enclosed will be prefixed with the name of the component.

For example, a rule like div.alert { color: green } in a component named name="HelloBtn" that has been imported with namespace="mylib" would result in the following, fully-prefixed rule: mylib-HelloBtn a { color: blue }

Class isolation (`<Component mode="vanish"...`)

By default, components have "regular" rendering mode. If you've configured your component to instead use "vanish" rendering or "vanish-into-document", it will to make the component function as basically a one-time template that "vanishes" away after rendering, leaving only it's children. When this mode is set, the Style CPart will enable class-based isolation.

The technique for this is the most involved of the three isolation modes: It will modify your resulting DOM to add a class, by default generated from the Component name, to every referenced element. Finally, it will change the style sheet to only select elements that have this new class.

Example: If there is a style like p.quote strong, in a component named mylib-HelloBtn, then it will re-use the component name as a CSS class to the which it adds to the strong element specified. Then it will use the :is() CSS selector is used to join the class, resulting in the CSS of: .mylib-HelloBtn:is(p.quote strong)

Shadow DOM isolation (`<Component mode="shadow"...`)

By default, components have "regular" rendering mode. If you've configured your component to instead use "Shadow DOM" rendering to protect it from getting outside CSS applied to it, then the Style will be "encapsulated" or inserted in the "shadow root" of component instances, as opposed to the document root. (More on this here: MDN's "ShadowRoot.styleSheets")

When using Shadow DOM, both the stylesheet and DOM will NOT be modified. Instead, the CSS will automatically be isolated by nature of the browser's shadow DOM CSS isolation feature. This isolates the component's DOM from the parent's styles, causing guaranteed CSS isolation. Keep in mind, however, it creates a new "open shadow root" DOM node, and prevents global styles (e.g. regular link tags) from being applied. If you prefer using shadow DOM for components, you can share base-style across shared Style components (browsers should notice repeated duplicate shadow DOM sheet insertions and should be optimized accordingly).

div.alert { color: green } in a component named name="HelloBtn" that has been imported with namespace="mylib" would result in the following, fully-prefixed rule: mylib-HelloBtn a { color: blue }

isolate-class - Force "isolate class" feature to be on, even if the component is not in a vanish-based rendering mode. component itself. This will work for both "regular" and "shadow" rendering mode. For example, in regular rendering mode, if you have the CSS :host { color: red } in a component named name="MyChart" that has been imported with namespace="mylib", then it would create the following, fully-prefixed CSS rule: mylib-MyChart { color: red } :host - Use the ":host" pseudo-element to select the component itself. This will work for both "regular" and "shadow" rendering mode. For example, in regular rendering mode, if you have the CSS :host { color: red } in a component named name="MyChart" that has been imported with namespace="mylib", then it would create the following, fully-prefixed CSS rule: mylib-MyChart { color: red }