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

To keep CSS separate and easier to debug, Modulo Style Component Parts provide handy utilities to "isolates" whatever CSS you provide it.

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 isolation_ (where the browser's Shadow DOM is used to isolate the styles of this component).

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: green }

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, where new classes are attached to elements to isolate your CSS. This is one of the most precise techniques for isolation - only affecting those elements that should be selected, while leaving children untouched.

The technique for this is the most involved of the three isolation modes: It will modify your resulting DOM to add a class to every referenced element. By default, the class name chosen will be the same as the Component tag name. Also, it will only add to elements that are referenced in your CSS. It will ignore any non-targeted elements. However, as a warning, it can still end up inflating your HTML size: E.g. if you have 100 paragraphs in a Component, all of the 100 paragraphs will get the 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: green }

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 }

Overriding isolation mode

Isolation mode is auto-detected by default, based on the component mode. However, the behavior can be overridden on a per-Style basis by using the -auto-isolate definition processor attribute.

Configuring Style

Style components "try to do the right thing", by autodetecting their behavior based on the Component configuration. However, sometimes it's necessary to override the auto-detection. Also, features like prefix-isolation are very useful in many web tasks while integrating legacy sites.

prefix - Used to specify prefix-based isolation.
- prefix="#chart_styles" - Prefix every selector in a CSS style sheet with#chartstyles, to keep it "isolated" within the HTML element withid="chartstyles`.
-auto-isolate - Set this to one of the component modes to override autodetection and force that behavior. The default value is true, which will autodetect based on the component mode as described above.
- Example: Set this to -auto-isolate="vanish" to force vanish-style isolation on a non-vanishing component
- Example: Set this to -auto-isolate:=false to totally turn off isolation.
isolate-class - Enables class-based isolation. You can use this property to override the class used as well.
- Example: Set this to isolate-class="my-component" to create a .my-component class to get added to all CSS selectors and relevant DOM elements
isolate-selector - Not typically useful, but this enables you to specify which elements you want to select with the isolate-class specified. By default, it will only be elements that are specified in CSS, but this is your chance to override that default behavior. - Example:isolate-selector="p,div"will only attempt to isolatepanddivtags if/when anisolate-class` is used
url-replace - 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.