Docs

Documentation versions (currently viewingVaadin 14)

You are viewing documentation for an older Vaadin version. View latest documentation

Theme Variants

Variants are opt-in features of each theme which affect the visual presentation of components. They do not affect their behavior or functionality.

Examples of variants include light and dark modes, density presets (compact, small, large), and visual prominence (primary, tertiary, no-borders).

Themes can define global and component-specific variants. Theme variants can be used across all Style Scopes – you don’t need to define or import them individually for each style scope.

Global Variants

Global variants affect all component instances in an application. Light and dark modes are good examples of global variants.

See the documentation for Lumo Variants and Material Variants to learn more about the built-in variants.

In server-side views (Java), use the variant attribute of the @Theme annotation. See Using Themes for more information.

Source code
UsingComponentThemes.java
ThemeVariants.js
ThemeVariants.html

Component Variants

Component variants affect selected component instances. Primary buttons, and small buttons and text fields are common examples of component variants. You can combine multiple variants together for a single component, for example a small primary button.

Many components have built-in variants in both the Lumo and the Material theme. See the documentation for Lumo Variants and Material Variants to learn more about the built-in variants.

Components which have built-in variants implement the HasTheme interface and have convenient Java APIs for using them. For other components, use the Element API and the setAttribute method.

Source code
UsingComponentThemes.java
ThemeVariants.js
ThemeVariants.html

Sub-component Variants

Theme variants propagate to sub-components. For example, the Combo Box component internally contains the Text Field component. Setting a theme variant on a Combo Box will also be applied on the internal Text Field component.

This also means, that even though Combo Box does not have a built-in “small” variant of its own, it can still utilize the built-in “small” variant of the Text Field component. For example:

In server-side views (Java):

Source code
UsingComponentThemes.java
ThemeVariants.js
ThemeVariants.html

See Styling Components to learn about the hierarchy of built-in Vaadin components, so you can use variants more effectively and know which exact components you need to target in order to customize components with sub-components.

Custom Variants

Custom variants allow you to freely customize the visual appearance of components. They are defined in an additional stylesheet which you import as component styles (see Importing Style Sheets). Technically, custom variants work exactly like built-in variants.

To create a custom variant, first we need to write the styles for that variant. For example, to create a new variant for Button, the following CSS would work:

Source code
CSS
:host([theme~="my-custom-variant"]) {
  /* Set the CSS properties you want to customize */
}

To learn how to correctly target internal parts of components and how to write the correct CSS selectors, see Styling Components.

Then, you need to import the style sheet into the corresponding component’s style scope. See Importing Style Sheets to learn more.

Finally, you can use the my-custom-variant on a Button component, as shown before.

89685B3D-DB88-461E-B3F1-D3C3B266C9C3