One of the main benefits of the Valo theme is that it allows you to customize it to your needs. Because it’s based on Web Components and Polymer, the styling is done a bit differently than for a traditional web page.
Depending on your needs, there are different options how to customize any element’s styles and theme.
For common use cases, Valo offers many built-in theme variations you can apply to individual element instances. For example, there is a “primary” theme for buttons, and a ”small” theme text-fields.
The built-in variations are applied using the theme attribute, and they work in any style scope:
The build-in variations of each component are documented in each element’s documentation page, where you can also view the source code how to apply them. See Button’s color variations for example.
Valo defines global and element specific CSS custom properties that you can use to make smaller adjustments to the theme.
The pages under the “Style guide” section (Colors for example) list the custom properties that affect all elements. Element specific custom properties are listed at the end of each element’s documentation page. See Button’s custom properties for example.
As an example, if you wish to adjust the border radius for all elements that are affected by
it, you can place the following code in the top level scope of you application (e.g.
index.html):
Use the <custom-style> element for
cross-browser compatility.
If you wish to adjust the border radius for vaadin-button specifically, you can
do the following:
But, there’s a catch – you need to place this <style> element in the same
style scope (i.e. shadow DOM) as the button you are trying to style. Normal CSS selectors,
like the vaadin-button tag selector here, will not affect elements inside other
style scopes (i.e. they are not able to style elements across shadow DOM boundaries).
To work around this limitation, we can target the button specific
--valo-button-border-radius custom property instead, and we can apply that in the
top level scope as well:
When you can’t accomplish the styling you want using the CSS custom properties provided by the theme, you can create new theme modules to add low level CSS for any element.
A theme module is basically the same as a
Polymer style module,
with an additional theme-for attribute.
The theme-for attribute specifies the element (read: Web Component) that the
styles in the theme module will affect. The value can be a space separated list of element names, and can contain wildcard element names as well.
Examples of valid theme-for attribute values:
The styles written inside a theme module are included in the elements shadow DOM. That means,
that in order to style the main element (a.k.a. the host element) you need to use the
:host selector:
In addition to the :host selector, the only other supported selectors inside a theme module are ones that target the documented “shadow parts” of the element. You can still write more complex selectors, which rely on any of the state attributes applied on the host or parts.
You can find links to the shadow parts documentation at the end of each element’s styling API documentation. See vaadin-button for example.
When creating a theme module for an element, the styles in that theme module will apply to all instances of that element. The styles are always “global” in that sense and can’t be scoped by default with anything.
There are two ways to scope the styles that you write in a theme module.
theme attribute). The downside of this approach is that you end up adding the styles to all instances, even though only some of them need those styles.As with the built-in element themes, theme modules should be defined before the corresponding elements are imported to make sure they are loaded by the elements.