Documentation

Documentation

Application Theme

Advice on using a theme for styling an application.

The recommended way to load CSS stylesheets for styling Vaadin components and other UI elements is to place them in an application theme folder. Themes created this way are always loaded on top of the default Lumo theme.

For use in a single application, the theme folder is placed inside the frontend/themes folder, with a name of your choosing. Vaadin application projects generated with Vaadin Start have a predefined theme folder with the same name as the project itself.

frontend
└── themes
    └── my-theme        (1)
        ├── styles.css  (2)
        └── theme.json  (3)

The theme folder (1) must contain a master stylesheet called styles.css (2). A theme configuration file called theme.json (3) is optional.

Themes built this way can be packaged as JAR files to be shared by multiple applications.

Note
The @CssImport annotation is not recommended.
In older versions of Vaadin, stylesheets were loaded using the @CssImport and @Stylesheet annotations — and in very old versions using the @HtmlImport annotation. While @CssImport and @Stylesheet still work, they’re no longer recommended as the primary way to load stylesheets.

Applying a Theme

The theme contained in the folder is applied to the UI using the @Theme annotation, with the name of the theme folder as a parameter. The @Theme annotation must be placed on the class that implements the AppShellConfigurator interface. This interface is used for configuring various application features. In projects generated with Vaadin Start, that’s the Application class.

@Theme("my-theme")
public class Application implements AppShellConfigurator {
  ...
}

To apply a custom theme on top of the Dark variant of Lumo, the variant is provided as an additional parameter, the annotation:

@Theme(value="my-theme", variant=Lumo.DARK)
public class Application implements AppShellConfigurator {
  ...
}
Note
Themes Cannot Be Switched Run-Time

Although the project may contain multiple theme folders, only one can be applied to the UI. There’s no way dynamically to switch theme folders run-time. However, there are ways to switch between variants of the same theme, load dynamically additional styles on top of the theme, and to create base-themes inherited by sub-themes.

Master Stylesheet

The master stylesheet, styles.css is loaded automatically into the UI. All CSS, including Lumo style property values and custom component styles, can be added there.

To apply Lumo style property modifications globally (i.e., in the whole application), they should be placed in a style block targeting the html root element selector like so:

html {
  --lumo-primary-color: green;
  --lumo-font-family: Times;
}

The master stylesheet is also a good place to define your own global style properties.

Additional Stylesheets

It can be useful to split CSS into multiple stylesheets, to avoid creating a mess in the master stylesheet. Additional stylesheets are loaded through @import directives at the top of the master stylesheet. They can be placed in sub-folders if desired.

@import 'colors.css';
@import 'views/admin-view.css';
@import 'input-fields/textfield.css';

html, :host() {
  …
}

It’s also possible to load stylesheets via external URLs, and from JAR dependencies and npm packages.

External Stylesheets

Stylesheets can be loaded from outside the application by URL using the same @import directive. This can be used, for example, to load font-face declarations or color palettes from outside the application.

@import url('https://example.com/some-external-styles.css');

html, :host() {
  …
}

Components Sub-Folder (Legacy Feature)

Stylesheets placed in a sub-folder called components in the application theme are loaded by default into the Shadow DOM of Vaadin components — that is to say, if their file names match the root element name of a component.

This is a legacy feature from earlier versions of Vaadin, in which Vaadin components were styled primarily though Shadow DOM CSS injection. Although this approach to component styling is no longer recommended, the injection mechanism is still supported and enabled by default. This is to ease migration from earlier versions.

Note
Disable Pre-Compiled Frontend Bundle

The loading of shadow DOM stylesheets from the components sub-folder is not compatible with the pre-compiled frontend bundle. In order to use this mechanism for loading shadow DOM styles, the pre-compiled bundled must be disabled.

This legacy feature, though, may cause problems in application themes based on the current recommended approach to component styling, if a sub-folder called components is used. The feature can, however, be disabled by setting the autoInjectComponents flag in the theme configuration file to false:

{
  "lumoImports" : [ "typography", "color", "spacing", "badge", "utility" ],
  "autoInjectComponents" : "false"
}

Images & Fonts

You can include font files and images in your theme folder. Create sub folders for them, i.e., images and fonts. You need to use the @font-face CSS rule to load font files, like the roboto.woff file located in my-theme/fonts/ in the example below.

@font-face {
  font-family: "Roboto";
  src: url("./fonts/roboto.woff") format("woff");
}

.application-logo {
  background-image: url("./img/logo.png");
}

It’s also possible to load images and fonts via external URLs, and from npm packages.

Note
Embedded Components

If the theme is to be used with embedded Flow applications or components, such as for use with Design System Publisher, @font-face declarations must be placed in a special stylesheet called document.css to ensure that they’re loaded to the page root rather than into a shadow root.

Images stored in the theme folder can also be used with Flow’s Image class using the path themes/[theme-name]/filename.png:

Image logo = new Image("themes/my-theme/images/logo.png", "Logo");

Theme Folder Structure Example

Below is an example of how a theme folder with images, fonts, and multiple stylesheets and sub-folders can look:

frontend
└── themes
    └── my-theme
        ├── component-styles
        │   ├── input-fields.css
        │   └── buttons.css
        ├── fonts
        │   └── roboto.woff
        ├── images
        │   ├── logo.png
        │   └── login-background.png
        ├── colors.css
        ├── fonts.css
        ├── styles.css
        └── theme.json

Theme Configuration

The theme configuration file, theme.json, can be used to configure various theme-related features. The most common of these is the lumoImports property, used to define which modules of the built-in Lumo theme are to be loaded.

{
  "lumoImports" : [ "typography", "color", "spacing", "badge", "utility" ]
}

The most common usage of this property is to enable Badge styles and the Lumo Utility Classes. If not defined, the following modules are loaded by default:

  • typography

  • color

  • sizing

  • spacing

Other theme configuration features are covered in the Advanced Styling Topics section:

e5e984e4-6a4f-40ab-a6fc-665166a2d8c5