Valo Theme

    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 http://vaadin.com/valo.

    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:

    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.

    $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-line-height(default:[literal]1.55)

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

    1. $v-line-height: 1.6;

    Font Settings

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

    Base font size. It should be specified in pixels.

    1. $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.

    1. $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 .

    $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.

    $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.

    1. $v-border-radius: 8px;

    $v-gradient(default:[literal]v-linear 8%)

    $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:

    1. $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 .

    $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, as described in .

    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

    For example:

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

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

      $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 for more details.

      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 http://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.

      1. $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:

      2.   font-family: 'Source Sans Pro', monospace;
      3. }

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

      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.

      1. 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 .

      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 , 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:

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

        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.