--- title: Creating and Using Themes order: 5 layout: page --- [[themes.creating]] = Creating and Using Themes Custom themes are placed in the [filename]#VAADIN/themes# folder of the web application, in an Eclipse project under the [filename]#WebContent# folder or [filename]#src/main/webapp# in Maven projects, as was illustrated in <>. 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. [[themes.creating.sass]] == 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 <>. To define a Sass theme with the name mytheme, you must place a file with name [filename]#styles.scss# in the theme folder [filename]#VAADIN/themes/mytheme#. If no [filename]#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 [filename]#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 [filename]#addons.scss# file. [[themes.creating.sass.scss]] === 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 [literal]#++@include++# them in the theme rule as follows: [source, 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 [literal]#++&++# to refer to the theme name. Otherwise, you can safely leave the nested theme selector out as follows: [source, 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. [source, css] ---- @import "../valo/valo.scss"; @mixin mytheme { @include valo; /* An actual theme rule */ .v-button { color: blue; } } ---- [[themes.creating.sass.addons]] === Add-on Themes Some Vaadin add-ons include Sass styles that need to be compiled into the theme. These are managed in the [filename]#addons.scss# file in a theme, included from the [filename]#styles.scss#. The [filename]#addons.scss# file is automatically generated by the Vaadin Plugin for Eclipse or Maven. [subs="normal"] ---- /* 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;** } ---- [[themes.creating.css]] == 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 [filename]#styles.css# file in the [filename]#VAADIN/themes/mytheme# folder. You need to import the [filename]#styles.css# of Valo theme as follows: ---- @import "../valo/styles.css"; .v-app { background: yellow; } ---- [[themes.creating.standard-components]] == 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 [methodname]#addStyleName()#. Notice that [methodname]#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, [literal]#++v-textfield++# style is used for all text input boxes in components, in addition to [classname]#TextField#. [[themes.creating.builtin]] == Built-in Themes Since version 8.0, Vaadin Framework includes only one built-in theme: * [literal]#++valo++#, the primary theme since Vaadin 7.3 The following legacy themes can be found in the [filename]#vaadin-compatibility-themes.jar# package for easier migrating from framework version 7 to 8: * [literal]#++reindeer++#, the primary theme in Vaadin 6 and 7 * [literal]#++chameleon++#, an easily customizable theme * [literal]#++runo++#, the default theme in IT Mill Toolkit 5 * [literal]#++base++#, which was never to be used directly, but is the base for other legacy themes The themes are provided in the respective [filename]#VAADIN/themes/<theme>/styles.scss# stylesheets in the [filename]#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 [package]#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 <>. ifdef::web[] [NOTE] .Serving Built-In Themes Statically ==== The built-in themes included in the Vaadin library JAR are served dynamically from the JAR by the servlet. Serving themes and widget sets statically by the web server is more efficient. To do so, you need to extract the [filename]#VAADIN/# directories from the JAR to the web content directory ( [filename]#WebContent# in Eclipse or [filename]#src/main/webapp# in Maven projects). [subs="normal"] ---- [prompt]#$# [command]#cd# WebContent ---- [subs="normal"] ---- [prompt]#$# [command]#unzip# path-to/vaadin-server-8.x.x.jar 'VAADIN/*' ---- [subs="normal"] ---- [prompt]#$# [command]#unzip# path-to/vaadin-themes-8.x.x.jar 'VAADIN/*' ---- [subs="normal"] ---- [prompt]#$# [command]#unzip# path-to/vaadin-client-compiled-8.x.x.jar 'VAADIN/*' ---- You can also serve static content from a front-end caching server, which reduces the load of the application server. In portals, you install the themes globally in the portal in similar way, as described in <<../portal/portal-liferay#portal.liferay.install,"Installing Vaadin Resources">>. Just make sure to update the static content when you upgrade to a newer version of Vaadin. ==== endif::web[] Creation of a default theme for custom GWT widgets is described in <<../gwt/gwt-styling#gwt.styling,"Styling a Widget">>. [[themes.creating.addon]] == Add-on Themes You can find more themes as add-ons from the link:http://vaadin.com/directory[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 [filename]#addons.scss# file in the project theme folder. It should be included by the project theme.