Docs

Docs

Stylesheets

A guide on how to use stylesheets to style Vaadin applications.

Stylesheets are placed in the src/main/resources/META-INF/resources folder, and are loaded with the @StyleSheet annotation.

In most cases you should apply @StyleSheet annotations to the main application class that implements the AppShellConfigurator interface. This ensures that the CSS in it is applied globally, up-front, when the application UI is loaded into the browser.

Source code
Java
@StyleSheet("styles.css")
public class Application implements AppShellConfigurator {
 ...
}

You can split your CSS over multiple stylesheets, and load them either with separate @StyleSheet annotations, or load additional stylesheets using the CSS @import rule.

Source code
src/main/resources/META-INF/resources/styles.css
@import "additional-styles.css";

/* your CSS goes here */

Stylesheets are applied to your UI in the order in which the @StyleSheet annotations and @import rules occur in your code.

External Stylesheets

All of the above methods for loading stylesheets also allow you to load stylesheets from external URIs, including other domains, by supplying an absolute path to @StyleSheet or @import.

Source code
Java
@StyleSheet("styles.css")
@StyleSheet("https://example.com/external-styles.css")
public class Application implements AppShellConfigurator {
 ...
}
Source code
src/main/resources/META-INF/resources/styles.css
@import "https://example.com/external-styles.css";

You can read more about the @import at-rule on MDN.

Lazy-Loading Stylesheets

If you want to delay the loading of a particular stylesheet until it’s needed – for example if the stylesheet is big and only needed in a particular view or Flow component – you can apply the @StyleSheet annotation to its class instead of the main application class.

Source code
Java
@StyleSheet("calendar-view.css")
public class CalendarView extends VerticalLayout {
  ...
}

Note that the stylesheet will remain loaded even after the user navigates away from the view, or when the component is no longer displayed, so you still need to ensure that the styles in it are scoped appropriately. You can use CSS class names to scope styles to a particular view or other part of the UI.

Source code
Java
@StyleSheet("calendar-view.css")
public class CalendarView extends VerticalLayout {
  public CalendarView() {
    addClassName("calendar-view");
  }
}
Source code
src/main/resources/META-INF/resources/calendar-view.css
.calendar-view {
  /* style rules in here only apply to CalendarView */
  vaadin-button {
    --aura-accent-color: green;
  }
}
Note
CSS Class Names
CSS class names are identifier-attributes applied to HTML elements in order to scope CSS styling to them. The same class name can be applied to multiple elements, and each element can have multiple class names. They have nothing to do with Java or TypeScript classes.

Stylesheets can also be loaded and unloaded dynamically through Java code.

Spring Security

If you are using Spring Security in your Vaadin application, you need to ensure that your stylesheets are accessible to unauthenticated users. The default Vaadin Spring Security configuration only permits access to src/main/resources/META-INF/resources/styles.css as well as the Aura and Lumo theme stylesheets.

To allow access to additional stylesheets, you can modify your Spring Security configuration like so:

Source code
Java
public class SecurityConfig {
    @Bean
    SecurityFilterChain securityFilterChain(HttpSecurity http) throws Exception {
        http.with(VaadinSecurityConfigurer.vaadin(), configurer -> {
            ...
        });

        // Permit access to common static resource paths
        http.authorizeHttpRequests(auth -> {
            auth.requestMatchers(PathRequest.toStaticResources().atCommonLocations()).permitAll();
        });

        return http.build();
    }

    ...
}

This allows access to common locations for static resources, one of which is the css path. To make stylesheets available under that path, place them in the src/main/resources/META-INF/resources/css folder. For example, if you place a stylesheet in src/main/resources/META-INF/resources/css/additional-styles.css, you can import it in your main stylesheet like so:

Source code
src/main/resources/META-INF/resources/styles.css
@import "css/additional-styles.css";

When using lazy-loading, you can load the stylesheet with @StyleSheet like so:

Source code
Java
@StyleSheet("css/additional-styles.css")
public class SomeView extends VerticalLayout {
    ...
}

caa5a55d-8bd0-425b-94dc-521a018a2e1b