Skip to content
javahacks.dev
Vaadin

Vaadin Theme and Styling for Application Look and Feel

Theme a Vaadin application: choose Lumo or Aura, change design tokens with CSS custom properties, add a custom theme folder and style components with parts.

5 min read
Summarize in AI
Flat illustration of a browser page built from server-side components, with the Vaadin, Spring, Thymeleaf and HTML5 logos.

A Vaadin application looks decent by default, and a company's product needs its own colours, type and spacing. Vaadin's styling is built on CSS custom properties, which makes most changes small and keeps them upgrade-safe. This guide covers the theme folder, the design tokens that carry most of the look, your own classes, theme variants, dark mode, reaching into component internals when tokens are not enough, and fonts. It is written for Vaadin 25 and the Lumo base theme.

The theme folder

Text
src/main/frontend/themes/orders/
  theme.json
  styles.css
  components/vaadin-button.css

Activate it on the application shell:

java
@Theme("orders")
public class AppShell implements AppShellConfigurator { }

styles.css holds global rules. A file under components/ named after a component is injected into that component's shadow DOM, which is how you reach its internals. theme.json can list assets and additional stylesheets. Keep the theme in version control and treat it as code: changes go through review, and a screenshot of the main views belongs in the pull request.

Design tokens

CSS
html {
  --lumo-primary-color: #0a6c74;
  --lumo-primary-text-color: #0a6c74;
  --lumo-font-family: "Inter", system-ui, sans-serif;
  --lumo-border-radius-m: 6px;
  --lumo-space-m: 1rem;
}

Every Vaadin component reads these variables, so one change recolours buttons, focus rings and selections together. The properties cover colour, size, space, typography, shadows and radius. Prefer tokens over rewriting component CSS, because tokens survive an upgrade: a rule that targets a component's internal structure can break when that structure changes, while a variable keeps its meaning. When you change the primary colour, check the contrast of text on it, and set the text colour variables to match. A brand colour that fails the contrast ratio looks fine on a designer's screen and is unreadable for users with low vision.

Your own classes

java
Div card = new Div(new H3("Revenue"), chart);
card.addClassName("card");
CSS
.card {
  background: var(--lumo-base-color);
  border: 1px solid var(--lumo-contrast-10pct);
  border-radius: var(--lumo-border-radius-l);
  padding: var(--lumo-space-l);
}

Use the Lumo variables inside your rules and the card follows the colour scheme automatically. Utility classes from Lumo, such as padding-m or flex, avoid some custom CSS for spacing and layout. Name your own classes for what they are, like card or kpi, not for how they look, like blue-box, so a later redesign needs no renames.

Theme variants

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

TextField search = new TextField();
search.addThemeVariants(TextFieldVariant.LUMO_SMALL);

Variants are the built-in alternatives for a component: primary or tertiary buttons, small fields, borderless grids. They are the designed way to change a component's appearance, the component ships with them, and they carry through dark mode. Use a variant before you write CSS, and write CSS only for what no variant offers.

Dark mode

java
@Theme(variant = Lumo.DARK)
public class AppShell implements AppShellConfigurator { }

You can also toggle the theme attribute on the document element at run time:

java
UI.getCurrent().getPage().executeJs("document.documentElement.setAttribute('theme', $0)", "dark");

Write your own colours with tokens such as var(--lumo-base-color) so they flip with the scheme, the same principle as a semantic token layer in any design system. A hard-coded #ffffff in your stylesheet is the classic cause of a card that stays white in dark mode. Remember the user's choice: store it in local storage and apply it before the first paint, to avoid a flash of the wrong scheme.

Reaching into a component

A component's shadow DOM blocks outside selectors. Use the parts it exposes:

CSS
vaadin-grid::part(header-cell) { font-weight: 600; }

Or, for deeper changes, use the file under components/:

CSS
:host([theme~="compact"]) [part~="cell"] { padding: 2px 8px; }

The documentation for each component lists its parts and state attributes. Selecting internal elements by tag name works until an update changes them, so a part or a state attribute is the contract and everything else is an accident. Leave a comment above each such rule naming the component version it was written for, so the upgrade review knows where to look.

Fonts and assets

Add self-hosted fonts to the theme and reference them with @font-face in styles.css. Loading fonts from your own origin avoids an extra DNS lookup, keeps pages working offline and removes a third party from the privacy picture. Use font-display: swap so text shows immediately in a fallback face. Check the result in the production build rather than in dev mode, because asset handling differs; see the production build.

Checking the result

Look at the application in three states: the default scheme, dark mode and a narrow window. A design token change tends to look right on the page where you made it and wrong on a view you forgot, such as a dialog or a notification, which render in overlays outside the normal tree. Open each overlay type once. Run an automated contrast check on the main views too, since the primary colour is used for text on a white background and for white text on the primary colour, and a value that works for one often fails the other.

Organising the stylesheet

Keep styles.css for tokens and a handful of layout classes, and move anything per component into the components/ folder, one file per component. A single large stylesheet becomes a dumping ground within a year. A short comment at the top of each file stating what it changes and why gives the next person a reason to delete a rule once the underlying issue is fixed upstream.

Spacing, density and responsive layouts

The spacing tokens (--lumo-space-xs to --lumo-space-xl) set rhythm for the whole application, and a compact variant tightens components for data-heavy screens. Decide density once, at the theme level, so a table-heavy admin view and a form do not each invent their own padding. Media queries in styles.css handle narrow windows: collapse a side drawer, stack form columns and let grids scroll horizontally. Test with the browser's device toolbar, since layout bugs on a phone are the ones teammates on desktops never see.

When to ask a designer

Tokens cover colour, type and spacing well. They do not make a layout good. If the application has more than a dozen screens, ask for a small set of reference screens from a designer, and build the theme to match them, instead of tuning variables by eye.

Sharing the theme across applications

If several Vaadin applications need the same look, publish the theme as a separate module and reference it from each application, so a change is made once.

What theming does not do

Theming is for the look. Layout and navigation are a separate topic, covered in routing and layouts. A custom web component needs its own parts and tokens, as in custom components. The reference is the Vaadin styling documentation, and CSS custom properties on MDN explain the mechanism underneath.

Share

Keep reading

Get new posts by email

We send one email when a new post is published. No spam.

Unsubscribe in one click. No spam, ever.