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.
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 }
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 }