Documentation

You are viewing documentation for Vaadin 23. View latest documentation

Documentation

@Theme Annotation

Describes how to use the @Theme annotation.

The @Theme annotation is used to define the theme to use for your application. You can use it to enable one of Lumo’s built-in light or dark themes, or to define your own custom theme.

Consider the following when you use the @Theme annotation:

  • By default, Vaadin applications use the light variant of Lumo. You don’t need to use the @Theme annotation if you want to use this theme.

  • The annotation should be present only once for an app, in a class implementing the AppShellConfiguration interface. That is, only a single theme can be defined and having multiple instances throws an exception.

  • Custom themes declared using the @Theme annotation are always based on Lumo theme.

  • You can use @Theme to declare a custom theme that’s based on the light or dark variant of Lumo.

  • If needed, you can disable the Lumo theme for your application using the @NoTheme annotation. However, this isn’t recommended for most applications, as it’s easier to extend the Lumo theme than to create a brand new theme.

Usage

The @Theme annotation must be added on a class that implements the AppShellConfigurator interface.

For example, in a Spring Boot application, you can explicitly enable Lumo’s dark variant by implementing the AppShellConfigurator interface in the main Application class, and then adding the @Theme annotation to it:

Source code
Application.java
@Theme(variant = Lumo.DARK) 1
@SpringBootApplication
public class Application extends SpringBootServletInitializer implements AppShellConfigurator { 2

  public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

  1. The @Theme annotation can be used to enable one of Lumo’s built-in light or dark variants, or to define your own custom theme. In this example, the annotation is being used to enable Lumo’s dark variant.

  2. The @Theme annotation can only be added once in the application on top of a class that implements the AppShellConfigurator interface.

In a plain-Java project, the annotation can be used in a class that looks something like the following:

Source code
MyAppShell.java
@Theme("my-theme") 1
public class MyAppShell implements AppShellConfigurator { 2
}

  1. In this example, the @Theme annotation is used to declare a custom theme called my-theme.

  2. The @Theme annotation must always be used on a class implementing AppShellConfigurator.

Enabling Lumo Dark Mode

By default, Lumo uses the light variant of the theme. You can enable the dark variant by using the @Theme annotation and setting the variant property to Lumo.DARK.

Source code
Application.java
@Theme(variant = Lumo.DARK) 1
@SpringBootApplication
public class Application extends SpringBootServletInitializer implements AppShellConfigurator {

  public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }

}

  1. Enabling Lumo’s dark variant by using the @Theme annotation.

Read more about Lumo’s light and dark modes in the Lumo variants guide.

Declaring a Custom Theme

You can also use the @Theme annotation to declare a custom theme.

Source code
Application.java
@Theme(value = "my-theme") 1
@SpringBootApplication
public class Application extends SpringBootServletInitializer implements AppShellConfigurator {
  public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

  1. The @Theme annotation is used to declare the name of the custom theme (in this case, the "my-theme" custom theme). This custom theme is applied on top of the default Lumo theme.

Custom themes are always based on the Lumo theme, which is in light mode by default. If you want to, you can use the @Theme annotation to declare a custom theme that’s based on the dark variant of Lumo.

Source code
Application.java
@Theme(value = "my-theme", variant = Lumo.DARK) 1
@SpringBootApplication
public class Application extends SpringBootServletInitializer implements AppShellConfigurator {
  public static void main(String[] args) {
        SpringApplication.run(Application.class, args);
    }
}

  1. The @Theme annotation is used to declare a custom theme called "my-theme" on top of the Lumo’s dark variant.

38DEDF5E-84D4-4AEF-A9CA-FBF817CC3070