Docs

Docs

Application Theme

Recommendations on using a theme for styling an application.

It’s best to put CSS stylesheets for styling Vaadin components and other UI elements in an application theme folder. Themes organization this way are loaded on top of the default Lumo theme.

For use in a single application, place your theme folder in the frontend/themes directory. Vaadin application projects generated with Vaadin Start have a pre-defined theme folder with the same name as the project.

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
Flow @CssImport Annotation
In older versions of Vaadin, stylesheets were loaded using @CssImport and @Stylesheet annotations. In much older versions, they were loaded using the @HtmlImport annotation. Although @CssImport `and `@Stylesheet still work, they’re recommended only for loading stylesheets into custom standalone components — not as the primary way to load application styles.

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. For projects generated with Vaadin Start, that would be 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 at Run-Time
Although a project may contain multiple theme folders, only one can be applied to the UI. There’s no way dynamically to switch theme folders at 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.

@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 a 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 — 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 through 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 bundle 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’ll 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 a 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 in the page root rather than in 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. The example below loads an image file from a theme folder called, my-theme:

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 undefined, the following modules are loaded by default:

  • typography

  • color

  • sizing

  • spacing

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

Embedded application theming is covered in Theming Embedded Applications.

You can find an example project that demonstrates the application theme in action at GitHub.

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