Documentation versions (currently viewingVaadin 24)

CSS Loading Order

Understanding 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 orders. That is, their priorities 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. The Lumo theme.

  2. Application-specific bundled CSS added with a `@CssImport'.

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

  4. Application-specific unbundled CSS added with @StyleSheet.

  5. Parent theme.

  6. Current theme.

The Lumo theme isn’t loaded and applied if another theme class is provided (for example, @Theme(themeClass = MyCustomTheme.class)), or if the @NoTheme annotation is used.

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

The "current theme" is the theme used in your application. It can be a theme created locally or packaged as a JAR dependency. See Application Theme and Using a Theme in Multiple Applications 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 this, the style for the loading indicator should be defined in frontend/index.html explicitly using the .v-loading-indicator CSS selector.