CSS Loading Order

A theme is the recommended way to organize styles in a Vaadin application. However, the other ways to import styles, namely the CSSImport and StyleSheet annotations, are still supported. Styles applied with different approaches have different loading order. That is, the priority they are computed in the browser and possibly override each other.

To keep the application theming and styles consistent and well-formed, it’s important to consider the loading order of the following CSS sources:

  1. Lumo theme

  2. Application-specific bundled CSS added with a @CssImport, as descibed in Importing Bundled Style Sheets (if used)

  3. Styles added on Java side via Page::addStylesheet (if used)

  4. Application-specific unbundled CSS added with @StyleSheet, as descibed in Importing External Style Sheets (if used)

  5. Parent theme (if used)

  6. Current theme

Lumo theme won’t be loaded and applied if another theme class is provided, namely the @Theme(themeClass = MyCustomTheme.class), or if @NoTheme found.

The parent theme is an existing theme whose styles and variables the current theme inherits.

"Current theme" is the theme used in your application. It can be a theme created locally or packaged as a jar dependency. See Creating a Custom Theme for more information.

Styles with a higher loading order have a higher precedence. For example, the following style, if placed in global.css within the theme folder frontend/themes/my-theme, overrides the default Lumo font size 1rem with 0.875rem:

html {
    --lumo-font-size-m: 0.875rem;
By default, a loading indicator is shown at the top of the viewport after a delay. If a theme modifies the loading indicator style, the new style is applied in the middle of the loading progress. To avoid that, style for the loading indicator should be defined in frontend/index.html explicitly via .v-loading-indicator CSS selector.