path: root/documentation/themes/themes-creating.asciidoc

---
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
<<themes-overview#figure.themes.theme-contents,"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.

[[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
<<themes-compiling#themes.compiling,"Compiling Sass Themes">>.

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 distinquishable 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,
unlike you can Valo, for example. 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]#legacy-styles.css# of the built-in theme as follows:


----
@import "../reindeer/legacy-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.

//TODO add reference to a Firebug section when available

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

Vaadin currently includes the following built-in themes:

* [literal]#++valo++#, the primary theme since Vaadin 7.3
* [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]#++liferay++#, for Liferay portlets

In addition, there is the [literal]#++base++# theme, which should not be used
directly, but is extended by the other built-in themes, except valo.

The built-in themes are provided in the respective
[filename]#VAADIN/themes/&lt;theme&gt;/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.


----
@Theme("runo")
public class MyUI extends UI {
    @Override
    protected void init(VaadinRequest request) {
        ...
        Panel panel = new Panel("Regular Panel in the Runo Theme");
        panel.addComponent(new Button("Regular Runo Button"));

        // A button with the "small" style
        Button smallButton = new Button("Small Runo Button");
        smallButton.addStyleName(Runo.BUTTON_SMALL);

        Panel lightPanel = new Panel("Light Panel");
        lightPanel.addStyleName(Runo.PANEL_LIGHT);
        lightPanel.addComponent(
            new Label("With addStyleName(\"light\")"));
        ...
----

The example with the Runo theme is shown in
<<figure.themes.creating.builtin.runo>>.

[[figure.themes.creating.builtin.runo]]
.Runo Theme
image::img/builtin-runo.png[]

The built-in themes come with a custom icon font, FontAwesome, which is used for
icons in the theme, and which you can use as font icons, as described in
<<dummy/../../../framework/themes/themes-fonticon#themes.fonticon,"Font
Icons">>.

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-7.x.x.jar 'VAADIN/*'
----
[subs="normal"]
----
[prompt]#$# [command]#unzip# path-to/vaadin-themes-7.x.x.jar 'VAADIN/*'
----
[subs="normal"]
----
[prompt]#$# [command]#unzip# path-to/vaadin-client-compiled-7.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
<<dummy/../../../framework/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
<<dummy/../../../framework/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.