Docs

Vaadin 8 reached End of Life on February 21, 2022. Discover how to make your Vaadin 8 app futureproof →

Docs

Valo Theme

Valo is the word for light in Finnish. The Valo theme incorporates the use of light in its logic, in how it handles shades and highlights. It creates lines, borders, highlights, and shadows adaptively according to a background color, always with contrasts pleasant to human visual perception. Auxiliary colors are computed using an algorithmic color theory to blend gently with the background. The static art is complemented with responsive animations.

The true power of Valo lies in its configurability with parameters, functions, and Sass mixins. You can use the built-in definitions in your own themes or override the defaults. Detailed documentation of the available mixins, functions, and variables can be found in the Valo API documentation available at https://vaadin.com/api/valo/.

Basic Use

Valo is used just like other themes. Its optional parameters must be given before the @import statement.

Your project theme file, such as mytheme.scss, included from the styles.scss file, could be as follows:

// Modify the base color of the theme
$v-background-color: hsl(200, 50%, 50%);

// Import valo after setting the parameters
@import "../valo/valo";

.mythemename {
  @include valo;

  // Your theme's rules go here
}

If you need to override mixins or function definitions in the valo theme, you must do that after the import statement, but before including the valo mixin. Also, with some configuration parameters, you can use variables defined in the theme. In this case, they need to be overridden after the import statement.

Common Settings

In the following, we describe the optional parameters that control the visual appearance of the Valo theme. In addition to the ones given here, component styles have their own parameters, listed in the sections describing the components in the other chapters.

General Settings

$v-background-color(default:[literal]hsl(210, 0%, 98%))

The background color is the main control parameter for the Valo theme and it is used for computing all other colors in the theme. If the color is dark (has low luminance), light foreground colors that give high contrast with the background are automatically used.

You can specify the color in any way allowed in CSS: hexadecimal RGB color code, RGB/A value specified with rgb() or rgba(), HSL/A value specified with hsl() or hsla(). You can also use color names, but it should be avoided, as not all CSS color names are currently supported.

$v-app-background-color(default:$v-background-color)

Background color of the UI’s root element. You can specify the color in any way allowed in CSS.

$v-app-loading-text(default:[literal]"")

A static text that is shown under the loading spinned while the client-side engine is being loaded and started. The text must be given in quotes. The text can not be localized currently.

$v-app-loading-text: "Loading Resources...";
$v-line-height(default:[literal]1.55)

Base line height for all widgets. It must be given a unitless number.

$v-line-height: 1.6;

Font Settings

$v-font-size(default:[literal]16px)

Base font size. It should be specified in pixels.

$v-font-size: 18px;
$v-font-weight(default:[literal]300)

Font weight for normal fonts. The size should be given as a numeric value, not symbolic.

$v-font-weight: 400;
$v-font-color(default: computed)

Foreground text color, specified as any CSS color value. The default is computed from the background color so that it gives a high contrast with the background.

$v-font-family(default:[literal]"Open Sans", sans-serif)

Font family and fallback fonts as a comma-separated list. Font names containing spaces must be quoted. The default font Open Sans is a web font included in the Valo theme. Other used Valo fonts must be specified in the list to enable them. See Valo Fonts.

$v-font-family: "Source Sans Pro", sans-serif;
$v-caption-font-size(default:[literal]round($v-font-size * 0.9))

Font size for component captions. The value should be a pixel value.

$v-caption-font-weight(default:[literal]max(400, $v-font-weight))

Font weight for captions. It should be defined with a numeric value instead of symbolic.

Layout Settings

$v-unit-size (default: round(2.3 * $v-font-size)) This is the base size for various layout measures. It is directly used in some measures, such as button height and layout margins, while other measures are derived from it. The value must be specified in pixels, with a suitable range of 18-50. $v-unit-size: 40px;$v-layout-margin-top$v-layout-margin-right$v-layout-margin-bottom$v-layout-margin-left (default: $v-unit-size) Layout margin sizes for all built-in layout components, when the margin is enabled with setMargin(), as described in . $v-layout-spacing-vertical and $v-layout-spacing-horizontal (default: round($v-unit-size/3)) Amount of vertical or horizontal space when spacing is enabled for a layout with setSpacing(), as described in .

Component Features

The following settings apply to various graphical features of some components.

$v-border(default:[literal]1px solid (v-shade 0.7))

Border specification for the components that have a border. The thickness measure must be specified in pixels. For the border color, you can specify any CSS color or one of the v-tint, v-shade, and v-tone keywords described later in this section.

$v-border-radius(default:[literal]4px)

Corner radius for components that have a border. The measure must be specified in pixels.

$v-border-radius: 8px;
$v-gradient(default:[literal]v-linear 8%)

Color gradient style for components that have a gradient. The gradient style may use the following keywords: v-linear and v-linear-reverse. The opacity must be given as percentage between 0% and 100%.

$v-gradient: v-linear 20%;
$v-bevel(default:[literal]inset 0 1px 0 v-tint, inset 0 -1px 0 v-shade)

Inset shadow style to define how some components are "raised" from the background. The value follows the syntax of CSS box-shadow, and should be a list of insets. For the bevel color, you can specify any CSS color or one of the v-tint, v-shade, and v-tone keywords described later in this section.

$v-bevel-depth(default:[literal]30%)

Specifies the "depth" of the bevel shadow, as applied to one of the color keywords for the bevel style. The actual amount of tint, shade, or tone is computed from the depth.

$v-shadow(default:[literal]0 2px 3px v-shade)

Default shadow style for all components. As with $v-bevel, the value follows the syntax of CSS box-shadow, but without the inset. For the shadow color, you can specify any CSS color or one of the v-tint or v-shade keywords described later in this section.

$v-shadow-opacity(default:[literal]5%)

Specifies the opacity of the shadow, as applied to one of the color keywords for the shadow style. The actual amount of tint or shade is computed from the depth.

$v-focus-style(default:[literal]0 0 0 2px rgba($v-focus-color, .5))

Box-shadow specification for the field focus indicator. The space-separated values are the horizontal shadow position in pixels, vertical shadow position in pixels, blur distance in pixels, spread distance in pixels, and the color. The color can be any CSS color. You can only specify the color, in which case defaults for the position are used. rgba() or hsla() can be used to enable transparency.

For example, the following creates a 2 pixels wide orange outline around the field:

$v-focus-style: 0 0 0 2px orange;
$v-focus-color(default:[literal]valo-focus-color())

Color for the field focus indicator. The valo-focus-color() function computes a high-contrast color from the context, which is usually the background color. The color can be any CSS color.

$v-animations-enabled(default:[literal]true)

Specifies whether various CSS animations are used.

$v-hover-styles-enabled(default:[literal]true)

Specifies whether various :hover styles are used for indicating that mouse pointer hovers over an element.

$v-disabled-opacity(default:[literal]0.5)

Opacity of disabled components, as described in "Enabled".

$v-selection-color(default:[literal]$v-focus-color)

Color for indicating selection in selection components.

$v-default-field-width(default:[literal]$v-unit-size * 5)

Default width of certain field components, unless overridden with setWidth().

$v-error-indicator-color(default:[literal]#ed473b)

Color of the component error indicator, as described in "Error Indicator and Message".

$v-required-field-indicator-color(default:[literal]$v-error-indicator-color)

Color of the required indicator in field components.

Color specifications for $v-border, $v-bevel, and $v-shadow may use, in addition to CSS colors, the following keywords:

v-tint

Lighter than the background color.

v-shade

Darker than the background color.

v-tone

Adaptive color specification: darker on light background and lighter on dark background. Not usable in $v-shadow.

For example:

$v-border: 1px solid v-shade;

You can fine-tune the contrast by giving a weight parameter in parentheses:

$v-border: 1px solid (v-tint 2);
$v-border: 1px solid (v-tone 0.5);

Theme Compilation and Optimization

$v-relative-paths(default:[literal]true)

This flags specifies whether relative URL paths are relative to the currently parsed SCSS file or to the compilation root file, so that paths are correct for different resources. Vaadin theme compiler parses URL paths differently from the regular Sass compiler (Vaadin modifies relative URL paths). Use false for Ruby compiler and true for Vaadin Sass compiler.

$v-included-components(default: component list)

Theme optimization parameter to specify the included component themes, as described in Theme Optimization.

$v-included-additional-styles(default:[literal]$v-included-components)

Theme optimization parameter that lists the components for which the additional component stylenames should be included. See Component Styles for more details.

Valo Mixins and Functions

Valo uses Sass mixins and functions heavily to compute various theme features, such as colors and shades. Also, all component styles are mixins. You can use the built-in mixins or override them. For detailed documentation of the mixins and functions, please refer to the Valo API documentation available at https://vaadin.com/valo/api.

Valo Fonts

Valo includes the following custom fonts:

  • Open Sans

  • Source Sans Pro

  • Roboto

  • Lato

  • Lora

The used fonts must be specified with the $v-font-family parameter for Valo, in a fallback order. A font family is used in decreasing order of preference, in case a font with higher preference is not available in the browser. You can specify any font families and generic families that browsers may support. In addition to the primary font family, you can use also others in your application. To enable using the fonts included in Valo, you need to list them in the variable.

$v-font-family: 'Open Sans', sans-serif, 'Source Sans Pro';

Above, we specify Open Sans as the preferred primary font, with any sans-serif font that the browser supports as a fallback. In addition, we include the Source Sans Pro as an auxiliary font that we can use in custom rules as follows:

.v-label pre {
  font-family: 'Source Sans Pro', monospace;
}

This would specify using the font in any Label component with the PREFORMATTED content mode.

Component Styles

Many components have component-specific styles to make them smaller, bigger, and so forth. You can specify the component styles with addStyleName() using the constants defined in the ValoTheme enum.

table.addStyleName(ValoTheme.TABLE_COMPACT);

For a complete up-to-date list of component-specific styles, please refer to Vaadin API documentation on the ValoTheme enum. Some are also described in the component-specific styling sections.

Disabling Component Styles

Component styles are optional, but all are enabled by default. They can be enabled on per-component basis with the $v-included-additional-styles parameter. It defaults to $v-included-components and can be customized in the same way, as described in Theme Optimization.

Configuration Parameters

The following variables control some common component styles:

$v-scaling-factor—​tiny(default:[literal]0.75)

A scaling multiplier for TINY component styles.

$v-scaling-factor—​small(default:[literal]0.85)

A scaling multiplier for SMALL component styles.

$v-scaling-factor—​large(default:[literal]1.2)

A scaling multiplier for LARGE component styles.

$v-scaling-factor—​huge(default:[literal]1.6)

A scaling multiplier for HUGE component styles.

Theme Optimization

Valo theme allows optimizing the size of the compiled theme CSS by including the rules for only the components actually used in the application. The included component styles can be specified in the $v-included-components variable, which by default includes all components. The variable should include a comma-separated list of component names in lower-case letters. Likewise, you can specify which additional component styles, as described in Component Styles, should be included using the $v-included-additional-styles parameter and the same format. The list of additional styles defaults to $v-included-components.

For example, if your UI contains just VerticalLayout, TextField, and Button components, you could define the variable as follows:

$v-included-components:
    verticallayout,
    textfield,
    button;

You can use the remove() function reversely to remove just some component themes from the standard selection.

For example, with the following you can remove the theme definitions for the Calendar component:

$v-included-components: remove($v-included-components, calendar);

Note that in this case, you need to give the statement after the @import statement for the Valo theme, because it overrides a variable by using its value that is defined in the theme.