vaadin-framework/documentation/themes/themes-overview.asciidoc

---
title: Overview
order: 1
layout: page
---

[[themes.overview]]
= Overview

Vaadin separates the appearance of the user interface from its logic using
__themes__. Themes can include Sass or CSS style sheets, custom HTML layouts,
and any necessary graphics. Theme resources can also be accessed from
application code as [classname]#ThemeResource# objects.

Custom themes are placed under the [filename]#VAADIN/themes/# folder of the web
application (under [filename]#WebContent# in Eclipse or
[filename]#src/main/webapp# in Maven projects). This location is fixed -- the
[filename]#VAADIN# folder contains static resources that are served by the
Vaadin servlet. The servlet augments the files stored in the folder by resources
found from corresponding [filename]#VAADIN# folders contained in JARs in the
class path. For example, the built-in themes are stored in the
[filename]#vaadin-themes.jar#.

<<figure.themes.theme-contents>> illustrates the contents of a theme.

[[figure.themes.theme-contents]]
.Contents of a Theme
image::img/theme-contents-hi.png[]

The name of a theme folder defines the name of the theme. The name is used in
the [literal]#++@Theme++# annotation that sets the theme. A theme must contain
either a [filename]#styles.scss# for Sass themes, or [filename]#styles.css#
stylesheet for plain CSS themes, but other contents have free naming. We
recommend that you have the actual theme content in a SCSS file named after the
theme, such as [filename]#mytheme.scss#, to make the names more unique.

We also suggest a convention for naming the folders as [filename]#img# for
images, [filename]#layouts# for custom layouts, and [filename]#css# for
additional stylesheets.

Custom themes need to extend a base theme, as described in
<<dummy/../../../framework/themes/themes-creating#themes.creating,"Creating and
Using Themes">>. Copying and modifying an existing theme is also possible, but
it is not recommended, as it may need more work to maintain if the modifications
are small.

You use a theme by specifying it with the [literal]#++@Theme++# annotation for
the UI class of the application as follows:


[source, java]
----
@Theme("mytheme")
public class MyUI extends UI {
    @Override
    protected void init(VaadinRequest request) {
        ...
    }
}
----

A theme can contain alternate styles for user interface components, which can be
changed as needed.

In addition to style sheets, a theme can contain HTML templates for custom
layouts used with [classname]#CustomLayout#. See
<<dummy/../../../framework/layout/layout-customlayout#layout.customlayout,"Custom
Layouts">> for details.

Resources provided in a theme can also be accessed using the
[classname]#ThemeResource# class, as described in
<<dummy/../../../framework/application/application-resources#application.resources.theme,"Theme
Resources">>. This allows displaying theme resources in component icons, in the
[classname]#Image# component, and other such uses.