Migrating from Lumo to Aura

Jmix 3 uses Aura as the default theme for new projects and continues to support Lumo. After upgrading a Jmix 2 application, you can keep Lumo or migrate to Aura.

The easiest way to migrate is to use a new Jmix 3 Aura project as a reference. Its generated files provide the correct theme structure and styles for standard views.

Create a Reference Project

Create a blank project that uses the same Jmix version as the upgraded application. Select Aura as its theme.

Keep this project open during the migration. You will copy its theme files and compare its standard view descriptors with those in your application.

Copy the Aura Theme

Copy the generated Aura theme directory from the reference project to the upgraded application:

src/main/resources/META-INF/resources/themes/<reference-project>-aura

Rename the copied directory to <application-name>-aura. Inside it:

  • Rename <reference-project>.css to <application-name>.css.

  • Update the last import in styles.css to use the new file name.

The resulting directory should look like this:

src/main/resources/META-INF/resources/themes/<application-name>-aura
├── <application-name>.css
├── styles.css
└── view
    ├── login-view.css
    ├── main-view-top-menu.css
    └── main-view.css

Keep the old Lumo theme unchanged as a reference until the migration is complete. Do not copy its generated view styles over the Aura files.

Enable Aura

In the main application class, remove the @Theme annotation and theme-specific Lumo imports or stylesheet annotations.

Add the following imports:

import com.vaadin.flow.component.dependency.StyleSheet;
import com.vaadin.flow.theme.aura.Aura;
import io.jmix.flowui.theme.aura.JmixAura;

Add the Aura stylesheet annotations in this order:

@StyleSheet(Aura.STYLESHEET)
@StyleSheet(JmixAura.STYLESHEET)
@StyleSheet("themes/<application-name>-aura/styles.css")

Update Standard Views

Compare the application’s main and login view descriptors with the corresponding descriptors in the reference project. Copy theme-related class names that are missing, while preserving application-specific content.

For example, the generated main view assigns jmix-main-view-app-layout to appLayout and jmix-initial-layout to initialLayout.

Older main views may use Lumo utility classes to position userMenu:

<userMenu id="userMenu"
          themeNames="tertiary"
          classNames="ms-auto me-m">

Replace them with the class used by the generated Aura main-view styles:

<userMenu id="userMenu"
          themeNames="tertiary"
          classNames="jmix-main-view-user-menu">

Migrate Custom Styles

Move application-specific CSS rules from the old theme to <application-name>.css. Also copy any images, fonts, and other assets used by those rules. Keep the application CSS import last in styles.css so that it can override the generated view styles.

Review the migrated code for the following Lumo-specific features:

Lumo utility classes

Aura does not include Lumo utility classes. Replace LumoUtility constants and Lumo utility class names with component APIs, custom CSS classes, or suitable constants from io.jmix.flowui.theme.StyleUtility.

CSS custom properties

Replace --lumo- properties according to their purpose. There is no direct replacement for every Lumo property. Use common --vaadin- properties where possible and Aura properties for theme-wide settings.

Customization Aura property

Accent color

--aura-accent-color-light and --aura-accent-color-dark

Application background

--aura-background-color-light and --aura-background-color-dark

Font family and size

--aura-font-family and --aura-base-font-size

Border radius

--aura-base-radius

Component density

--aura-base-size

See the Aura theme reference for the complete property list.

Component customizations

Review theme variants and Java constants with a LUMO_ prefix. Move rules from the old components directory to the application stylesheet because Vaadin 25 no longer injects these rules by default. See Styling UI Components.

Light and dark styles

Replace custom colors with Aura color properties or the CSS light-dark() function. A selector such as html[theme~='dark'] does not cover the LIGHT_DARK and DARK_LIGHT system modes. See Writing Color-Scheme-Aware CSS.

Rebuild and Test

Remove generated files before rebuilding the frontend bundle:

./gradlew clean vaadinClean

Start the application in development mode. Check the login view, main view, and customized components. If the application supports both color schemes, test both light and dark modes.

For a JAR deployment, test a production build:

./gradlew -Pvaadin.productionMode=true bootJar

Verify that the application stylesheet and its assets are loaded in the packaged application.

Remove the Old Theme

After the application works correctly in development and production modes, delete the old Lumo theme directory.