Creating and Using Themes

Custom themes are placed in the VAADIN/themes folder of the web application, in an Eclipse project under the WebContent folder or src/main/webapp in Maven projects, as was illustrated in “Contents of a Theme”. This location is fixed. You need to have a theme folder for each theme you use in your application, although applications rarely need more than a single theme.

Sass Themes

You can use Sass themes in Vaadin in two ways, either by compiling them to CSS by yourself or by letting the Vaadin servlet compile them for you on-the-fly when the theme CSS is requested by the browser, as described in “Compiling Sass Themes”.

To define a Sass theme with the name mytheme, you must place a file with name styles.scss in the theme folder VAADIN/themes/mytheme. If no styles.css exists in the folder, the Sass file is compiled on-the-fly when the theme is requested by a browser.

We recommend that you organize the theme in at least two SCSS files so that you import the actual theme from a Sass file that is named more uniquely than the styles.scss, to make it distinguishable in the editor. This organization is how the Vaadin Plugin for Eclipse creates a new theme.

If you use Vaadin add-ons that contain themes, Vaadin Plugin for Eclipse and Maven automatically add them to the addons.scss file.

Theme SCSS

We recommend that the rules in a theme should be prefixed with a selector for the theme name. You can do the prefixing in Sass by enclosing the rules in a nested rule with a selector for the theme name.

Themes are defined as Sass mixins, so after you import the mixin definitions, you can @include them in the theme rule as follows:

CSS

@import "addons.scss";
@import "mytheme.scss";
.mytheme {
  @include addons;
  @include mytheme;
}

However, this is mainly necessary if you use the UI in portlets, each of which can have its own theme, or in the special circumstance that the theme has rules that use empty parent selector & to refer to the theme name.

Otherwise, you can safely leave the nested theme selector out as follows:

CSS

@import "addons.scss";
@import "mytheme.scss";
@include addons;
@include mytheme;

The actual theme should be defined as follows, as a mixin that includes the base theme.

CSS

@import "../valo/valo.scss";
@mixin mytheme {
  @include valo;
  /* An actual theme rule */
  .v-button {
    color: blue;
  }
}

Add-on Themes

Some Vaadin add-ons include Sass styles that need to be compiled into the theme. These are managed in the addons.scss file in a theme, included from the styles.scss. The addons.scss file is automatically generated by the Vaadin Plugin for Eclipse or Maven.

/* This file is automatically managed and will be
   overwritten from time to time. /
/ Do not manually edit this file. /
/* Provided by vaadin-spreadsheet-1.0.0.beta1.jar */ @import "../../../VAADIN/addons/spreadsheet/spreadsheet.scss";
/ Import and include this mixin into your project
   theme to include the addon themes */
@mixin addons {
  @include spreadsheet;
}

Plain Old CSS Themes

In addition to Sass themes, you can create plain old CSS themes. CSS theme are more restricted than Sass styles - you can’t parameterize CSS themes in any way. Further, an application can only have one CSS theme while you can have multiple Sass themes.

A CSS theme is defined in a styles.css file in the VAADIN/themes/mytheme folder. You need to import the styles.css of Valo theme as follows:

@import "../valo/styles.css";
.v-app {
    background: yellow;
}

Styling Standard Components

Each user interface component in Vaadin has a CSS style class that you can use to control the appearance of the component. Many components have additional sub-elements that also allow styling. You can add context-specific stylenames with addStyleName(). Notice that getStyleName() returns only the custom stylenames, not the built-in stylenames for the component.

Please see the section on each component for a description of its styles. Most of the style names are determined in the client-side widget of each component. The easiest way to find out the styles of the elements is to use a HTML inspector such as FireBug.

Some client-side components or component styles can be shared by different server-side components. For example, v-textfield style is used for all text input boxes in components, in addition to TextField.

Built-in Themes

Since version 8.0, Vaadin Framework includes only one built-in theme:

• valo, the primary theme since Vaadin 7.3

The following legacy themes can be found in the vaadin-compatibility-themes.jar package for easier migrating from framework version 7 to 8:

• reindeer, the primary theme in Vaadin 6 and 7

• chameleon, an easily customizable theme

• runo, the default theme in IT Mill Toolkit 5

• base, which was never to be used directly, but is the base for other legacy themes

The themes are provided in the respective VAADIN/themes/<theme>/styles.scss stylesheets in the vaadin-themes JAR. Also the precompiled CSS files are included, in case you want to use the themes directly.

Various constants related to the built-in themes are defined in the theme classes in com.vaadin.ui.themes package. These are mostly special style names for specific components.

public class MyUI extends UI {
    @Override
    protected void init(VaadinRequest request) {
        ...
        Panel panel = new Panel("Regular Panel in the Valo Theme");
        panel.addComponent(new Button("Regular Valo Button"));
        // A button with the "small" style
        Button smallButton = new Button("Small Valo Button");
        smallButton.addStyleName(ValoTheme.BUTTON_SMALL);
        Panel lightPanel = new Panel("Borderless Panel");
        lightPanel.addStyleName(ValoTheme.PANEL_BORDERLESS);
        lightPanel.addComponent(
            new Label("With addStyleName(\"light\")"));
        ...

The Valo theme comes with a custom icon font, VaadinIcons, which you can use as font icons, as described in “Font Icons”.

$ cd WebContent

$ unzip path-to/vaadin-server-8.x.x.jar ‘VAADIN/‘

$ unzip path-to/vaadin-themes-8.x.x.jar ‘VAADIN/‘

$ unzip path-to/vaadin-client-compiled-8.x.x.jar ‘VAADIN/*’

Creation of a default theme for custom GWT widgets is described in “Styling a Widget”.

Add-on Themes

You can find more themes as add-ons from the Vaadin Directory. In addition, many component add-ons contain a theme for the components they provide.

The add-on themes need to be included in the project theme. Vaadin Plugin for Eclipse and Maven automatically include them in the addons.scss file in the project theme folder. It should be included by the project theme.