Theming Web Components

This chapter gives an overview of everything you need to understand in order to master and be productive in theming modern web applications which are built with web components.

First, it is important to draw the line between global styles and scoped styles:

  • Before web components were introduced, the styles were global on the web, meaning that a selector in CSS can target any element in the document.

  • Web components, and Shadow DOM in particular, introduce style scoping to the web platform. The contents of web components are isolated from global styles, and instead have scoped styles, which are specific to a particular web component only.

This guide describes how to apply global and scoped styles, as well as how to share common styles between style scopes for the application theming purpose.

Global Styles

Global styles are styles defined in the document scope. Global styles can target document body and any regular DOM contents inside, including the application views, but can not target Shadow DOM contents, such as internals of Vaadin components, Polymer templates, and other web components. To define global styles, use <custom-style><style>…​</style><custom-style> tags in HTML.

Note
Using the <custom-style> wrapper for global styles is required by Polymer to enable correct cross-browser scoping.

Place your global styles in a separate HTML file:

src/main/webapp/frontend/styles/shared-styles.html

  1. <custom-style>
  2.   <style>
  3.     /* Example global style */
  4.     html {
  5.       font-size: 1em;
  6.     }
  7.   </style>
  8. </custom-style>

As shown in the previous chapter, this file should be imported to the root layout level of your application.

Styling Polymer Templates

Since Polymer templates are web components, their template contents end up in Shadow DOM. By design, Shadow DOM defines a local style scope, isolated from global styles.

Scoped styles, which are specific to a single template, can be added directly to the <style> tag inside the template:

src/main/webapp/frontend/src/my-view.html

  1. <link rel="import" href="../bower_components/polymer/polymer-element.html">
  3. <dom-module id="my-view">
  4.   <template>
  5.     <style>
  6.       /* Example scoped styles, applied to <my-view> template contents only */
  8.       :host {
  9.         /* Styles for the `<my-view>` hosting element */
  10.         display: block;
  11.       }
  13.       .my-view-title {
  14.         font-weight: bold;
  15.         border-bottom: 1px solid gray;
  16.       }
  17.     </style>
  19.     <div class="my-view-title">My view title</div>
  20.   </template>
  21. </dom-module>
  22. <script>
  23.   class MyView extends Polymer.Element {
  24.     static get is() { return 'my-view'; }
  25.   }
  27.   customElements.define(MyView.is, MyView);
  28. </script>

Using Custom CSS Properties

One of the needs for theming is to share common style values, such as sizes, colors, etc, between pieces of the application. This could be achieved using custom CSS properties, which is a special syntax for assigning and referencing CSS variables. Custom CSS properties are inherited, their values cross Shadow DOM boundaries. Polymer templates can reuse values defined by global styles, as well as override them.

Use global styles for html element to define a global custom CSS property:

src/main/webapp/frontend/styles/shared-styles.html

  1. <custom-style>
  2.   <style>
  3.     html {
  4.       /* Example global custom CSS property definition */
  5.       --my-theme-color: brown;
  6.     }
  7.   </style>
  8. </custom-style>

For referencing your custom CSS property, use `var(--my-property)` syntax. For example, in your Polymer template styles:

src/main/webapp/frontend/src/my-view.html

  1. <!-- ... -->
  3. <dom-module id="my-view">
  4.   <template>
  5.     <style>
  6.       /* ... */
  8.       .my-view-title {
  9.         /* Example referencing custom CSS property */
  10.         color: var(--my-theme-color);
  11.       }
  12.     </style>
  13.   </template>
  15.   <!-- ... -->
  16. </dom-module>

Using Style Modules

Style modules allow sharing the same stylesheet between multiple Polymer templates and global styles.

Style modules are defined in HTML using `<dom-module id="my-styles"><template><style>/* …​ */</style></template></dom-module>` tag combination:

src/main/webapp/frontend/styles/shared-styles.html

  1. <dom-module id="shared-styles">
  2.   <template>
  3.     <style>
  4.       /* Example style module */
  5.       .my-outline-style {
  6.         outline: 1px solid green;
  7.       }
  8.     </style>
  9.   </template>
  10. </dom-module>

To include a style module in a Polymer template, import the module file with HTML imports and use `<style include="module-id">` :

src/main/webapp/frontend/src/my-view.html

  1. <!-- ... -->
  2. <link rel="import" href="../styles/shared-styles.html">
  4. <dom-module id="my-view">
  5.   <template>
  6.     <style include="shared-styles">
  7.       /*  */
  8.     </style>
  9.   </template>
  11.   <!-- ... -->
  12. </dom-module>
Note
Use a space-separated list of style module ids to include multiple style modules into a single scope: <style include=”shared-styles other-shared-styles”></style>.

Style modules can also be included in global styles:

src/main/webapp/frontend/styles/global-styles.html

  1. <link rel="import" href="./shared-styles.html">
  3. <custom-style>
  4.   <style include="shared-styles"></style>
  5. </custom-style>