> Markdown version of [Theme Variants](https://vaadin.com/docs/v14/flow/styling/theme-variants). Section index: [llms.txt](https://vaadin.com/docs/v14/flow/llms.txt)

# 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](https://vaadin.com/docs/v14/flow/styling/style-scopes.md) – you don’t need to define or import them individually for each style scope.

## <a id="global-variants"></a>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](https://vaadin.com/docs/v14/flow/styling/lumo/variants.md) and [Material Variants](https://vaadin.com/docs/v14/flow/styling/material/variants.md) to learn more about the built-in variants.

In server-side views (Java), use the `variant` attribute of the `@Theme` annotation. See [Using Themes](https://vaadin.com/docs/v14/flow/styling/using-themes.md) for more information.

**Java** — `UsingComponentThemes.java`

```java
@Theme(value = Lumo.class, variant = Lumo.DARK)
```

In client-side views (JavaScript), set the `theme` attribute on the `document.documentElement` object.

**JavaScript** — `ThemeVariants.js`

```javascript
document.documentElement.setAttribute("theme", "dark");
```

In client-side templates (HTML), set the `theme` attribute on the `<html>` element.

**HTML** — `ThemeVariants.html`

```html
<html theme="dark">
```

## <a id="component-variants"></a>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](https://vaadin.com/docs/v14/flow/styling/lumo/variants.md) and [Material Variants](https://vaadin.com/docs/v14/flow/styling/material/variants.md) 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](https://vaadin.com/docs/v14/flow/element-api/tutorial-properties-attributes.md) and the `setAttribute` method.

**Java** — `UsingComponentThemes.java`

```java
// Using the high-level HasTheme API
Button button = new Button("Themed button");
button.addThemeVariants(ButtonVariant.LUMO_PRIMARY,
        ButtonVariant.LUMO_SMALL);

Button button = new Button("Themed button");
button.getThemeNames().addAll(Arrays.asList("primary", "small"));

// Using the low-level Element API
Button button = new Button("Themed button");
String themeAttributeName = "theme";
String oldValue = button.getElement().getAttribute(themeAttributeName);
String variantsToAdd = "primary small";
button.getElement().setAttribute(themeAttributeName,
        oldValue == null || oldValue.isEmpty() ?
                variantsToAdd
                : ' ' + variantsToAdd);
```

In client-side JavaScript views, use the standard `setAttribute` DOM method to set the `theme` attribute value.

**JavaScript** — `ThemeVariants.js`

```javascript
const button = document.createElement('vaadin-button');
button.textContent = 'Themed button';
button.setAttribute('theme', 'primary small');
```

In client-side HTML templates, use the `theme` attribute value.

**HTML** — `ThemeVariants.html`

```html
<vaadin-button theme="primary small">Themed button</vaadin-button>
```

## <a id="sub-component-variants"></a>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):

**Java** — `UsingComponentThemes.java`

```java
ComboBox comboBox = new ComboBox();
comboBox.getElement().setAttribute("theme", TextFieldVariant.LUMO_SMALL.getVariantName());
```

In client-side views (JavaScript):

**JavaScript** — `ThemeVariants.js`

```javascript
const comboBox = document.createElement('vaadin-combo-box');
comboBox.setAttribute('theme', 'small');
```

In client-side templates (HTML):

**HTML** — `ThemeVariants.html`

```html
<vaadin-combo-box theme="small"></vaadin-combo-box>
```

See [Styling Components](https://vaadin.com/docs/v14/flow/styling/styling-components.md#sub-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.

## <a id="custom-variants"></a>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](https://vaadin.com/docs/v14/flow/styling/importing-style-sheets.md)). 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:

```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](https://vaadin.com/docs/v14/flow/styling/styling-components.md).

Then, you need to import the style sheet into the corresponding component’s style scope. See [Importing Style Sheets](https://vaadin.com/docs/v14/flow/styling/importing-style-sheets.md#component-local-scope) to learn more.

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

`89685B3D-DB88-461E-B3F1-D3C3B266C9C3`
