0
# Theming and Styling
1

2
Vaadin provides a comprehensive theming system with built-in themes, CSS custom properties, and component variants. The theming system supports both design systems (Lumo, Material) and custom styling approaches.
3

4
## Core Imports
5

6
```java
7
// Theme configuration annotations
8
import com.vaadin.flow.theme.Theme;
9
import com.vaadin.flow.theme.AbstractTheme;
10

11
// Lumo theme
12
import com.vaadin.flow.theme.lumo.Lumo;
13
import com.vaadin.flow.theme.lumo.LumoUtility;
14

15
// Material theme
16
import com.vaadin.flow.theme.material.Material;
17

18
// Component theming interfaces
19
import com.vaadin.flow.component.HasTheme;
20
import com.vaadin.flow.component.shared.ThemeVariant;
21

22
// Component theme variants
23
import com.vaadin.flow.component.button.ButtonVariant;
24
import com.vaadin.flow.component.textfield.TextFieldVariant;
25
import com.vaadin.flow.component.grid.GridVariant;
26
import com.vaadin.flow.component.dialog.DialogVariant;
27
import com.vaadin.flow.component.notification.NotificationVariant;
28

29
// Styling interfaces
30
import com.vaadin.flow.component.HasStyle;
31
import com.vaadin.flow.dom.Style;
32
import com.vaadin.flow.dom.ThemeList;
33

34
// CSS value enums
35
import com.vaadin.flow.dom.Style.Display;
36
import com.vaadin.flow.dom.Style.Position;
37

38
// Icon system
39
import com.vaadin.flow.component.icon.Icon;
40
import com.vaadin.flow.component.icon.VaadinIcon;
41

42
// Theme management
43
import com.vaadin.flow.component.UI;
44
import com.vaadin.flow.dom.Element;
45

46
// JavaScript modules for themes
47
import com.vaadin.flow.component.dependency.JsModule;
48

49
// Standard Java types
50
import java.util.Collections;
51
import java.util.HashMap;
52
import java.util.List;
53
import java.util.Map;
54
import java.util.Set;
55
import java.util.stream.Stream;
56
```
57

58
## Built-in Themes
59

60
### Lumo Theme
61

62
Modern design system with light and dark variants, serving as Vaadin's default theme.
63

64
```java { .api }
65
// Lumo theme is automatically included with Vaadin Platform
66
// No explicit import needed - automatically applied to all components
67

68
// Access Lumo CSS custom properties programmatically
69
public class LumoUtility {
70
    // Color properties
71
    public static final String PRIMARY_COLOR = "--lumo-primary-color";
72
    public static final String ERROR_COLOR = "--lumo-error-color";
73
    public static final String SUCCESS_COLOR = "--lumo-success-color";
74

75
    // Spacing properties
76
    public static final String SPACE_XS = "--lumo-space-xs";
77
    public static final String SPACE_S = "--lumo-space-s";
78
    public static final String SPACE_M = "--lumo-space-m";
79
    public static final String SPACE_L = "--lumo-space-l";
80
    public static final String SPACE_XL = "--lumo-space-xl";
81

82
    // Typography properties
83
    public static final String FONT_FAMILY = "--lumo-font-family";
84
    public static final String FONT_SIZE_S = "--lumo-font-size-s";
85
    public static final String FONT_SIZE_M = "--lumo-font-size-m";
86
    public static final String FONT_SIZE_L = "--lumo-font-size-l";
87
}
88
```
89

90
### Material Theme
91

92
Material Design implementation providing Material Design 3 styling.
93

94
```java { .api }
95
// To use Material theme, add dependency and import
96
// Dependency: com.vaadin:vaadin-material-theme
97

98
@Theme("material")
99
public class MaterialApp extends Component {
100
    // Application using Material theme
101
}
102

103
// Material theme CSS custom properties
104
public class MaterialUtility {
105
    public static final String PRIMARY_COLOR = "--material-primary-color";
106
    public static final String SURFACE_COLOR = "--material-surface-color";
107
    public static final String ON_SURFACE_COLOR = "--material-on-surface-color";
108
}
109
```
110

111
## Theme Configuration
112

113
### @Theme Annotation
114

115
Configure application theme and variant.
116

117
```java { .api }
118
@Target(ElementType.TYPE)
119
@Retention(RetentionPolicy.RUNTIME)
120
public @interface Theme {
121
    String value() default "";
122
    String variant() default "";
123
    Class<? extends AbstractTheme> themeClass() default AbstractTheme.class;
124
}
125
```
126

127
### Theme Variants
128

129
Global theme variants for dark mode and component density.
130

131
```java { .api }
132
// Apply theme variants to the application
133
@Theme(variant = Lumo.DARK)
134
public class DarkModeApp extends Component {
135
}
136

137
@Theme(variant = Lumo.COMPACT)
138
public class CompactApp extends Component {
139
}
140

141
// Lumo theme constants
142
public final class Lumo {
143
    public static final String DARK = "dark";
144
    public static final String LIGHT = "light";
145
    public static final String COMPACT = "compact";
146
}
147
```
148

149
## Component Theming
150

151
### HasTheme Interface
152

153
Interface for components that support theme variants.
154

155
```java { .api }
156
public interface HasTheme {
157
    void addThemeVariants(ThemeVariant... variants);
158
    void removeThemeVariants(ThemeVariant... variants);
159
    void setThemeName(String themeName);
160
    String getThemeName();
161
    void setThemeName(String themeName, boolean set);
162
    boolean hasThemeName(String themeName);
163
    void addThemeName(String themeName);
164
    void removeThemeName(String themeName);
165
    Set<String> getThemeNames();
166
}
167
```
168

169
### Component Theme Variants
170

171
Theme variants for individual components.
172

173
```java { .api }
174
// Button variants
175
public enum ButtonVariant implements ThemeVariant {
176
    LUMO_PRIMARY,           // Primary button styling
177
    LUMO_SECONDARY,         // Secondary button styling
178
    LUMO_TERTIARY,          // Tertiary button styling
179
    LUMO_TERTIARY_INLINE,   // Inline tertiary styling
180
    LUMO_SUCCESS,           // Success color variant
181
    LUMO_ERROR,             // Error color variant
182
    LUMO_CONTRAST,          // High contrast variant
183
    LUMO_ICON,              // Icon-only button
184
    LUMO_SMALL,             // Small size variant
185
    LUMO_LARGE              // Large size variant
186
}
187

188
// TextField variants
189
public enum TextFieldVariant implements ThemeVariant {
190
    LUMO_SMALL,             // Small size variant
191
    LUMO_ALIGN_CENTER,      // Center-aligned text
192
    LUMO_ALIGN_RIGHT        // Right-aligned text
193
}
194

195
// Grid variants
196
public enum GridVariant implements ThemeVariant {
197
    LUMO_NO_BORDER,         // Remove outer border
198
    LUMO_NO_ROW_BORDERS,    // Remove row borders
199
    LUMO_ROW_STRIPES,       // Alternating row colors
200
    LUMO_COLUMN_BORDERS,    // Add column borders
201
    LUMO_COMPACT,           // Compact row height
202
    LUMO_WRAP_CELL_CONTENT  // Allow cell content wrapping
203
}
204

205
// Dialog variants
206
public enum DialogVariant implements ThemeVariant {
207
    LUMO_NO_PADDING         // Remove default padding
208
}
209

210
// Notification variants
211
public enum NotificationVariant implements ThemeVariant {
212
    LUMO_PRIMARY,           // Primary color
213
    LUMO_CONTRAST,          // High contrast
214
    LUMO_SUCCESS,           // Success color
215
    LUMO_ERROR              // Error color
216
}
217
```
218

219
## CSS Custom Properties
220

221
### Setting Custom Properties
222

223
Programmatically set CSS custom properties for theming.
224

225
```java { .api }
226
// Set CSS custom properties on components
227
public void configureCustomProperties(Component component) {
228
    component.getStyle().set("--custom-color", "#FF5722");
229
    component.getStyle().set("--custom-spacing", "16px");
230
    component.getStyle().set("--custom-border-radius", "8px");
231
}
232

233
// Set global CSS custom properties
234
public void configureGlobalProperties() {
235
    UI.getCurrent().getElement().getStyle().set("--lumo-primary-color", "#1976D2");
236
    UI.getCurrent().getElement().getStyle().set("--lumo-font-family", "Roboto, sans-serif");
237
}
238
```
239

240
### Lumo CSS Custom Properties
241

242
Complete set of Lumo theme custom properties.
243

244
```java { .api }
245
// Color properties
246
public static final String LUMO_PRIMARY_COLOR = "--lumo-primary-color";
247
public static final String LUMO_PRIMARY_COLOR_50PCT = "--lumo-primary-color-50pct";
248
public static final String LUMO_PRIMARY_COLOR_10PCT = "--lumo-primary-color-10pct";
249
public static final String LUMO_ERROR_COLOR = "--lumo-error-color";
250
public static final String LUMO_ERROR_COLOR_50PCT = "--lumo-error-color-50pct";
251
public static final String LUMO_ERROR_COLOR_10PCT = "--lumo-error-color-10pct";
252
public static final String LUMO_SUCCESS_COLOR = "--lumo-success-color";
253
public static final String LUMO_SUCCESS_COLOR_50PCT = "--lumo-success-color-50pct";
254
public static final String LUMO_SUCCESS_COLOR_10PCT = "--lumo-success-color-10pct";
255

256
// Typography properties
257
public static final String LUMO_FONT_FAMILY = "--lumo-font-family";
258
public static final String LUMO_FONT_SIZE_XXS = "--lumo-font-size-xxs";
259
public static final String LUMO_FONT_SIZE_XS = "--lumo-font-size-xs";
260
public static final String LUMO_FONT_SIZE_S = "--lumo-font-size-s";
261
public static final String LUMO_FONT_SIZE_M = "--lumo-font-size-m";
262
public static final String LUMO_FONT_SIZE_L = "--lumo-font-size-l";
263
public static final String LUMO_FONT_SIZE_XL = "--lumo-font-size-xl";
264
public static final String LUMO_FONT_SIZE_XXL = "--lumo-font-size-xxl";
265
public static final String LUMO_FONT_SIZE_XXXL = "--lumo-font-size-xxxl";
266
public static final String LUMO_LINE_HEIGHT_XS = "--lumo-line-height-xs";
267
public static final String LUMO_LINE_HEIGHT_S = "--lumo-line-height-s";
268
public static final String LUMO_LINE_HEIGHT_M = "--lumo-line-height-m";
269

270
// Spacing properties
271
public static final String LUMO_SPACE_XS = "--lumo-space-xs";
272
public static final String LUMO_SPACE_S = "--lumo-space-s";
273
public static final String LUMO_SPACE_M = "--lumo-space-m";
274
public static final String LUMO_SPACE_L = "--lumo-space-l";
275
public static final String LUMO_SPACE_XL = "--lumo-space-xl";
276

277
// Sizing properties
278
public static final String LUMO_SIZE_XS = "--lumo-size-xs";
279
public static final String LUMO_SIZE_S = "--lumo-size-s";
280
public static final String LUMO_SIZE_M = "--lumo-size-m";
281
public static final String LUMO_SIZE_L = "--lumo-size-l";
282
public static final String LUMO_SIZE_XL = "--lumo-size-xl";
283

284
// Border radius properties
285
public static final String LUMO_BORDER_RADIUS_S = "--lumo-border-radius-s";
286
public static final String LUMO_BORDER_RADIUS_M = "--lumo-border-radius-m";
287
public static final String LUMO_BORDER_RADIUS_L = "--lumo-border-radius-l";
288

289
// Box shadow properties
290
public static final String LUMO_BOX_SHADOW_XS = "--lumo-box-shadow-xs";
291
public static final String LUMO_BOX_SHADOW_S = "--lumo-box-shadow-s";
292
public static final String LUMO_BOX_SHADOW_M = "--lumo-box-shadow-m";
293
public static final String LUMO_BOX_SHADOW_L = "--lumo-box-shadow-l";
294
public static final String LUMO_BOX_SHADOW_XL = "--lumo-box-shadow-xl";
295
```
296

297
## Component Styling
298

299
### HasStyle Interface
300

301
Interface for components that support direct CSS styling.
302

303
```java { .api }
304
public interface HasStyle {
305
    Style getStyle();
306
    void setClassName(String className);
307
    String getClassName();
308
    void setClassName(String className, boolean set);
309
    void addClassName(String className);
310
    void removeClassName(String className);
311
    void addClassNames(String... classNames);
312
    void removeClassNames(String... classNames);
313
    boolean hasClassName(String className);
314
    Set<String> getClassNames();
315
}
316
```
317

318
### Style Object
319

320
Object for manipulating CSS styles programmatically.
321

322
```java { .api }
323
public class Style {
324
    // CSS property manipulation
325
    public Style set(String property, String value);
326
    public Style remove(String property);
327
    public Optional<String> get(String property);
328
    public boolean has(String property);
329

330
    // CSS class manipulation
331
    public Style setDisplay(Display display);
332
    public Style setPosition(Position position);
333
    public Style setWidth(String width);
334
    public Style setHeight(String height);
335
    public Style setMargin(String margin);
336
    public Style setPadding(String padding);
337
    public Style setColor(String color);
338
    public Style setBackground(String background);
339
    public Style setBorder(String border);
340
    public Style setFontSize(String fontSize);
341
    public Style setFontWeight(String fontWeight);
342
    public Style setTextAlign(String textAlign);
343
}
344

345
// CSS value enums
346
public enum Display {
347
    BLOCK, INLINE, INLINE_BLOCK, FLEX, GRID, NONE
348
}
349

350
public enum Position {
351
    STATIC, RELATIVE, ABSOLUTE, FIXED, STICKY
352
}
353
```
354

355
## Custom Theme Creation
356

357
### AbstractTheme Class
358

359
Base class for creating custom themes.
360

361
```java { .api }
362
public abstract class AbstractTheme implements Theme {
363
    public abstract String getBaseUrl();
364
    public abstract String getThemeUrl();
365

366
    public List<String> getHeaderInlineContents() {
367
        return Collections.emptyList();
368
    }
369

370
    public Map<String, String> getHtmlAttributes(String variant) {
371
        return Collections.emptyMap();
372
    }
373
}
374
```
375

376
### Custom Theme Implementation
377

378
Creating and registering custom themes.
379

380
```java { .api }
381
@JsModule("./themes/custom-theme/custom-theme.js")
382
@Theme("custom")
383
public class CustomTheme extends AbstractTheme {
384

385
    @Override
386
    public String getBaseUrl() {
387
        return "/themes/custom-theme/";
388
    }
389

390
    @Override
391
    public String getThemeUrl() {
392
        return "custom-theme.css";
393
    }
394

395
    @Override
396
    public Map<String, String> getHtmlAttributes(String variant) {
397
        Map<String, String> attributes = new HashMap<>();
398
        attributes.put("theme", "custom " + variant);
399
        return attributes;
400
    }
401
}
402
```
403

404
## Dark Mode Support
405

406
### Theme Variant Management
407

408
Programmatically manage theme variants including dark mode.
409

410
```java { .api }
411
public class ThemeManager {
412

413
    public void enableDarkMode() {
414
        UI.getCurrent().getElement().getThemeList().add(Lumo.DARK);
415
    }
416

417
    public void disableDarkMode() {
418
        UI.getCurrent().getElement().getThemeList().remove(Lumo.DARK);
419
    }
420

421
    public void toggleDarkMode() {
422
        ThemeList themeList = UI.getCurrent().getElement().getThemeList();
423
        if (themeList.contains(Lumo.DARK)) {
424
            themeList.remove(Lumo.DARK);
425
        } else {
426
            themeList.add(Lumo.DARK);
427
        }
428
    }
429

430
    public boolean isDarkMode() {
431
        return UI.getCurrent().getElement().getThemeList().contains(Lumo.DARK);
432
    }
433
}
434
```
435

436
### ThemeList Interface
437

438
Interface for managing theme variants on elements.
439

440
```java { .api }
441
public interface ThemeList {
442
    void add(String theme);
443
    boolean remove(String theme);
444
    boolean contains(String theme);
445
    void clear();
446
    void set(String theme, boolean set);
447
    void toggle(String theme);
448
    Stream<String> stream();
449
    int size();
450
}
451
```
452

453
## Icon Systems
454

455
### Vaadin Icons
456

457
Built-in icon system with 600+ icons.
458

459
```java { .api }
460
public enum VaadinIcon {
461
    // Navigation icons
462
    ARROW_LEFT, ARROW_RIGHT, ARROW_UP, ARROW_DOWN,
463
    CHEVRON_LEFT, CHEVRON_RIGHT, CHEVRON_UP, CHEVRON_DOWN,
464

465
    // Action icons
466
    PLUS, MINUS, CLOSE, CHECK, EDIT, DELETE, SEARCH,
467

468
    // File icons
469
    FILE, FOLDER, DOWNLOAD, UPLOAD, PRINT, COPY,
470

471
    // Communication icons
472
    PHONE, ENVELOPE, CHAT, COMMENT, BELL,
473

474
    // User icons
475
    USER, USERS, USER_CHECK, USER_STAR, GROUP,
476

477
    // Settings icons
478
    COG, TOOLS, WRENCH, SLIDERS, FILTER,
479

480
    // Status icons
481
    INFO_CIRCLE, WARNING, ERROR, SUCCESS, QUESTION_CIRCLE,
482

483
    // Media icons
484
    PLAY, PAUSE, STOP, FAST_FORWARD, BACKWARD,
485

486
    // Layout icons
487
    GRID, LIST, COLUMNS, VIEWPORT, EXPAND, CONTRACT;
488

489
    public Icon create();
490
    public String name();
491
}
492

493
public class Icon extends Component implements HasSize, HasStyle {
494
    public Icon(VaadinIcon icon);
495
    public Icon(String collection, String icon);
496

497
    public void setIcon(VaadinIcon icon);
498
    public void setIcon(String collection, String icon);
499
    public void setSize(String size);
500
    public void setColor(String color);
501
}
502
```
503

504
## Usage Examples
505

506
### Component Theme Variants
507

508
```java
509
// Apply theme variants to components
510
Button primaryButton = new Button("Primary Action");
511
primaryButton.addThemeVariants(ButtonVariant.LUMO_PRIMARY, ButtonVariant.LUMO_LARGE);
512

513
TextField smallField = new TextField("Small Field");
514
smallField.addThemeVariants(TextFieldVariant.LUMO_SMALL);
515

516
Grid<Person> grid = new Grid<>(Person.class);
517
grid.addThemeVariants(GridVariant.LUMO_ROW_STRIPES, GridVariant.LUMO_COMPACT);
518
```
519

520
### Custom Styling
521

522
```java
523
// Direct CSS styling
524
Component component = new Div();
525
component.getStyle()
526
    .set("background-color", "var(--lumo-primary-color)")
527
    .set("padding", "var(--lumo-space-m)")
528
    .set("border-radius", "var(--lumo-border-radius-m)");
529

530
// CSS class-based styling
531
component.addClassName("custom-component");
532
```
533

534
### Theme Switching
535

536
```java
537
public class ThemeSwitcher extends Component {
538
    private Button toggleButton = new Button("Toggle Dark Mode");
539

540
    public ThemeSwitcher() {
541
        toggleButton.addClickListener(e -> {
542
            ThemeList themeList = UI.getCurrent().getElement().getThemeList();
543
            boolean isDark = themeList.contains(Lumo.DARK);
544

545
            if (isDark) {
546
                themeList.remove(Lumo.DARK);
547
                toggleButton.setText("Enable Dark Mode");
548
            } else {
549
                themeList.add(Lumo.DARK);
550
                toggleButton.setText("Disable Dark Mode");
551
            }
552
        });
553
    }
554
}
555
```
556

557
### Custom CSS Properties
558

559
```java
560
// Define application-wide custom properties
561
public void configureCustomTheme() {
562
    Element body = UI.getCurrent().getElement();
563

564
    // Primary brand color
565
    body.getStyle().set("--app-primary-color", "#2563EB");
566
    body.getStyle().set("--app-primary-color-hover", "#1D4ED8");
567

568
    // Custom spacing scale
569
    body.getStyle().set("--app-space-xs", "4px");
570
    body.getStyle().set("--app-space-s", "8px");
571
    body.getStyle().set("--app-space-m", "16px");
572
    body.getStyle().set("--app-space-l", "24px");
573
    body.getStyle().set("--app-space-xl", "32px");
574

575
    // Custom component styling
576
    body.getStyle().set("--app-card-shadow", "0 4px 6px -1px rgba(0, 0, 0, 0.1)");
577
}
578
```
579

580
The theming system provides comprehensive control over application appearance while maintaining consistency and accessibility across all components.