--- title: Valo Theme order: 7 layout: page --- [[themes.valo]] = 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 http://vaadin.com/valo. [[themes.valo.use]] == Basic Use Valo is used just like other themes. Its optional parameters must be given before the [literal]#++@import++# statement. Your project theme file, such as [filename]#mytheme.scss#, included from the [filename]#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. [[themes.valo.variables]] == 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. [[themes.valo.variables.general]] === 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 [methodname]#rgb()# or [methodname]#rgba()#, HSL/A value specified with [methodname]#hsl()# or [methodname]#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; ---- [[themes.valo.variables.fonts]] === 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 <>. + ---- $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. [[themes.valo.variables.layout]] === 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 . ++++ [[themes.valo.variables.component]] === 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 [literal]#++v-tint++#, [literal]#++v-shade++#, and [literal]#++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: [literal]#++v-linear++# and [literal]#++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 [literal]#++v-tint++#, [literal]#++v-shade++#, and [literal]#++v-tone++# keywords described later in this section. + //TODO Check the meaning of v-tone $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 [literal]#++inset++#. For the shadow color, you can specify any CSS color or one of the [literal]#++v-tint++# or [literal]#++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. [methodname]#rgba()# or [methodname]#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 [methodname]#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 [literal]#++: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 <<../components/components-features#components.features.enabled,"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 [methodname]#setWidth()#. $v-error-indicator-color(default:[literal]#++#ed473b++#):: Color of the component error indicator, as described in <<../application/application-errors#application.errors.error-indicator,"Error Indicator and Message">>. $v-required-field-indicator-color(default:[literal]#++$v-error-indicator-color++#):: Color of the required indicator in field components. ifdef::vaadin7[] Field components are described in <<../components/components-fields#components.fields.field,"Field Interface">>. endif::vaadin7[] 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); ---- [[themes.valo.variables.optimization]] === 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 [literal]#++false++# for Ruby compiler and [literal]#++true++# for Vaadin Sass compiler. $v-included-components(default: component list):: Theme optimization parameter to specify the included component themes, as described in <>. $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. [[themes.valo.mixins]] == 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 http://vaadin.com/valo/api. [[themes.valo.fonts]] == 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 [classname]#Label# component with the [literal]#++PREFORMATTED++# content mode. [[themes.valo.component]] == Component Styles Many components have component-specific styles to make them smaller, bigger, and so forth. You can specify the component styles with [methodname]#addStyleName()# using the constants defined in the [classname]#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 [classname]#ValoTheme# enum. Some are also described in the component-specific styling sections. [[themes.valo.component.disabling]] === 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 <>. [[themes.valo.component.parameters]] === Configuration Parameters The following variables control some common component styles: $v-scaling-factor--tiny(default:[literal]#++0.75++#):: A scaling multiplier for [literal]#++TINY++# component styles. $v-scaling-factor--small(default:[literal]#++0.85++#):: A scaling multiplier for [literal]#++SMALL++# component styles. $v-scaling-factor--large(default:[literal]#++1.2++#):: A scaling multiplier for [literal]#++LARGE++# component styles. $v-scaling-factor--huge(default:[literal]#++1.6++#):: A scaling multiplier for [literal]#++HUGE++# component styles. [[themes.valo.optimization]] == 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 [literal]#++$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 [classname]#VerticalLayout#, [classname]#TextField#, and [classname]#Button# components, you could define the variable as follows: ---- $v-included-components: verticallayout, textfield, button; ---- You can use the [methodname]#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 [classname]#Calendar# component: ---- $v-included-components: remove($v-included-components, calendar); ---- Note that in this case, you need to give the statement __after__ the [literal]#++@import++# statement for the Valo theme, because it overrides a variable by using its value that is defined in the theme.