Component Variants

Many Vaadin components have so-called theme variants that provide different styles for the component. These are defined as part of the built-in Lumo and Material themes, and documented for each component.

For example, Button has a "primary" variant, which can be used as follows:

Button btn = new Button("Primary variant");
btn.addThemeVariants(ButtonVariant.LUMO_PRIMARY);

Multiple theme variants can be simultaneously applied to a component, although not all variants are designed to be used together.

Button btn = new Button("Primary + Small");
btn.addThemeVariants(ButtonVariant.LUMO_PRIMARY, ButtonVariant.LUMO_SMALL);

Variant Inheritance

Theme variants differ from CSS class names mainly in that they are automatically applied to sub-components within the shadow DOM of the component to which they are applied. For example, Combo Box contains a Text Field in its shadow DOM, so theme variants applied to a Combo Box are automatically passed down to the Text Field inside. This means that you can apply Text Field variants to a Combo Box even though Combo Box doesn’t have any variants of its own.

ComboBox cb = new ComboBox("Small Combo Box");

// Components without their own theme variant API have to
// use a different syntax for applying them:
cb.getThemeList().add(TextFieldVariant.LUMO_SMALL.getVariantName());

Variant inheritance only works for sub-components in the shadow DOM, not with regular “light DOM” children of a component. For example, Accordion Panel components inside an Accordion need to have their variants applied to each panel.

Custom Variants

You can define your own component theme variants using component-specific style sheets in a custom theme.

:host([theme~="rounded"]) {
  border-radius: 1em;
}

You can then apply the theme variant similarly to the built-in variants:

Button btn = new Button("Rounded");
btn.getThemeList().add("rounded");

These are inherited to sub-components similarly to the built-in variants.

See Styling Components to learn how to target the internal parts of Vaadin components.