Styling Overview

A brief overview of styling Vaadin applications.

Customizing Component Styles
Styling Other UI Elements
Locating & Loading Styles
Topics

This section contains a brief overview of the main aspects of styling Vaadin applications: how to customize the styling of Vaadin components; how to style other UI elements; and where to place your CSS code.

The other pages in the Styling section provide further details on these methods and other related topics.

Customizing Component Styles

The look and feel of Vaadin components is highly customizable in several ways.

Built-in Style Variants

Many Vaadin components come with built-in style variants that can be used to change the color, size, or other visual aspects of individual component instances through the addThemeVariants Java API.

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

See Browse Components for information on built-in style variants.

Customizing Style Properties

The default styling of Vaadin components is based on style properties — customizable CSS values — in the default Lumo theme. They can be used to tweak colors, fonts, sizing, and other properties without writing custom CSS.

A small sample of Lumo style properties and their use in Vaadin components

Lumo Style Properties Example

Style properties can be customized by providing new values for them in a CSS stylesheet.

/* Global style values */
html {
  --lumo-primary-color: green;
  --lumo-font-family: "Roboto";
}

/* Scoped to a type of component */
vaadin-button {
  --lumo-font-family: "Courier";
}

Effects of Above Customizations

A style property value can have different scopes:

Global, which affects the entire application. It’s applied to the html selector.
Component type specific. It’s applied to the component’s root element selector
Component instances – specific to one or more – to which a particular CSS class name has been applied (as shown below)

Button specialButton = new Button("I'm special");
specialButton.addClassName("special");

/* Scoped to instances with a particular CSS class name */
vaadin-button.special {
  --lumo-primary-color: cyan;
}

Style properties are recommended as the primary approach to both Vaadin component style customization and custom CSS. They make it easier to achieve a consistent look and feel across the application.

See List of Lumo style properties and Styling components through style properties for more information on these properties.

Applying CSS to Components

If you need to customize a component in ways that cannot be achieved with Lumo style properties, you can apply custom CSS to the component in a stylesheet.

Each component has a Styling documentation page that lists the CSS selectors to use for targeting the component, its parts, and its states.

Some of the stylable parts of a Text Field component

CSS is applied to components in regular CSS stylesheets, typically in the application theme folder.

vaadin-text-field::part(input-field) {
  border: 1px solid gray;
}

vaadin-text-field[focused]::part(input-field) {
  border-color: blue;
}

Results of this CSS

CSS can be scoped to specific component instances by applying CSS class names to them.

TextField specialTextField = new TextField("I'm special");
specialTextField.addClassName("special");

vaadin-text-field.special::part(input-field) {
  border-color: orange;
}

See Styling components with CSS, Browse components to see their CSS selectors, and Applying CSS to specific component instances# with CSS class names for more information.

Styling Other UI Elements

Although Vaadin application UIs are built primarily using Vaadin components, native HTML elements, like <span> and <div>, are also often used for layout and custom UI structures. These can be styled with custom CSS, and with utility classes that bundle predefined styles as easy-to-use constants.

Applying CSS to HTML Elements

Custom CSS is applied to native HTML elements similarly to Vaadin components, by placing it in a stylesheet in the application theme folder. Styles can be scoped to individual instances of these elements by applying CSS class names to them using the addClassNames Java API.

Span warning = new Span("This is a warning");
warning.addClassName("warning");

span.warning {
  color: orange;
}

See Native HTML element classes in Flow and Applying CSS to native HTML elements for more information.

Applying Styles with Utility Classes

The Lumo Utility Classes are a set of predefined CSS classes (similar to Tailwind CSS) that can be used to apply styling to HTML elements without writing your own CSS.

Small sample of Lumo Utility Classes

The LumoUtility collection in Flow provides constants for each utility class. They are applied using the same addClassNames API as is used for custom CSS class names.

Span errorMsg = new Span("Error");
errorMsg.addClassNames(
  LumoUtility.TextColor.ERROR,
  LumoUtility.Padding.SMALL,
  LumoUtility.Background.BASE,
  LumoUtility.BoxShadow.XSMALL,
  LumoUtility.BorderRadius.LARGE
);

Effects of the above application of utility classes

Effects Application of these Utility Classes

Note	The Lumo utility classes are primarily designed to be used with native HTML elements, Vaadin layout components, and custom UI structures. Although some of them do work as expected on some Vaadin components, this is not their intended use. They can’t be used to style the inner parts of components.

See Lumo Utility Classes for more information.

Locating & Loading Styles

Style property customizations and custom CSS are both placed in CSS stylesheets, typically in the application’s theme folder. The theme folder is specified using the @Theme annotation.

A master stylesheet, named styles.css, is automatically loaded. If you wish to split your CSS into multiple stylesheets, these can be added via CSS @import directives in the master stylesheet.

frontend
└── themes
    └── my-theme
        ├── styles.css
        └── theme.json

@Theme("my-theme")
public class Application implements AppShellConfigurator {
  ...
}

Note that application projects generated with Vaadin Start have a theme folder applied by default.

Note

@CssImport is supported, but not recommended. In older versions of Vaadin, stylesheets were loaded using @CssImport and @Stylesheet annotations, and in very old versions using the @HtmlImport annotation. While @CssImport `and `@Stylesheet still work, they are no longer recommended as the primary way to load styles into the UI.

See Application theme folder for more information.

Topics

Lumo: Introduction to the built-in Lumo theme.
Application Theme: Advice on using a theme for styling an application.
Styling Vaadin Components: Explanation and examples on how to customize the styling of Vaadin components.
Styling Other UI Elements: Describes how to apply styles to common and uncommon HTML elements.
Advanced Styling Topics: Advanced topics on styling applications.
Legacy Styling Features: List of legacy styling features that shouldn’t be used.

Documentation