Release Notes

Version 2.10.1

Version Updates

The following versions have been updated:

Dependency New version Previous version

Vaadin

25.2.3 (Release Notes)

25.2.1

Karibu

2.7.1

2.7.0

JUnit

6.1.2 (Release Notes)

6.1.1

Components, UI Annotations and Aspects

  • @UIOpenDialogButton: dialog can now be shown conditionally
    The annotated method may now return null to indicate that no dialog should be opened under certain conditions. In this case, the binding context is still updated.

Version 2.10.0

The release notes contain changes compared to version 2.9.0.

Version Updates

The following versions have been updated:

Dependency

New version

Previous version

Vaadin

25.2.1 (Release Notes)

24.9.8

Faktor-IPS

26.7.0.release (Release Notes)

26.1.0.release

Karibu

2.7.0

2.5.0

Spring Boot compatibility tested for

4.1.0 (Release Notes)

3.5.9

Spring Framework

7.0.8 (Release Notes)

6.2.15

JUnit

6.1.1 (Release Notes)

5.14.2
Vaadin 25 Update

The update to Vaadin 25 not only brings an update of the tech stack, but also changes in build configuration and frontend styling.

Below are the most notable changes for linkki applications. For a complete list of Vaadin 25 breaking changes and migration steps, please refer to the Vaadin 25 Upgrade Guide.

Technical compatibilities

  • Spring Boot 4
    Vaadin 25 uses Spring Boot 4.1+ and Spring Framework 7. This is a major version jump from Spring Boot 3.5. Please refer to Spring Boot 4.0 Migration Guide for more information.

  • JakartaEE 11
    Vaadin 25 is compatible with Jakarta EE 11.

  • Node.js
    Frontend builds now require Node.js 24 or later for development.

  • JUnit
    All linkki test libraries now use JUnit 6. Apart from the Java 21 requirement, which is already mandatory since linkki 2.8, there should be no breaking API changes.
    For detailed changes and improvements, see JUnit 6 release notes.
    If you encounter any incompatibilities while using JUnit 5, please don’t hesitate to contact us.

  • Selenium
    Vaadin TestBench now uses Selenium 4.39.0.

Build and dependencies

  • Maven configuration
    The default in new projects is that mvn install builds a production artifact without needing a production profile.

    For development features, com.vaadin/vaadin-dev can be included as a dependency with optional scope. This module includes features that make the development faster such as live-reload. The server also sends more data to the browser to help troubleshoot problems in the server client communication. More details can be found in the Vaadin documentation.

    Migration: For JEE projects, no changes are needed.
    In Spring Boot projects, following changes should be made in all pom.xml that use vaadin-maven-plugin:

    • Profile production should be removed.

    • vaadin-maven-plugin should always call the goal build-frontend. Goal prepare-frontend should be removed.

    • Add the following dependency:

      <dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-dev</artifactId>
    <optional>true</optional>
</dependency>

  • Jackson for JSON handling
    Vaadin 25 replaced the deprecated elemental.json library with Jackson for JSON handling.
    Migration: This is an internal change in Vaadin and should not affect linkki applications directly, but may impact custom components using Vaadin’s JSON APIs.

  • Less transitive dependencies
    Some dependencies do not come with Vaadin anymore. If those dependencies are needed, they need to be included explicitly. Some well-known ones include:

    • Guava: Google Core Libraries

    • Apache Commons Compress

    Migration: Check if these dependencies are really required and include them as dependencies explicitly if needed.

Notable Java API Changes

  • Label component deprecation
    com.vaadin.flow.component.html.Label has been deprecated as the naming is confusing, making the component often misused in cases, where a <label> element should not be used.
    Migration: To ensure that <label> should really be used, check if the usage is correct according to the specification.
    If this is the case, use com.vaadin.flow.component.html.NativeLabel instead.
    If the usage does not match the specification, use a different element such as Text or Span instead.

  • Renaming of variant constants
    With the introduction of a new theme, variants that only work with Lumo theme are renamed, e.g. DetailsVariant.FILLED to DetailsVariant.LUMO_FILLED.
    Migration: Check the deprecation Javadoc and replace the constants accordingly.

Vaadin 25.1

  • Vaadin now uses Jackson for all JSON functionalities. Due to compatibility issues, Spring Boot 4.0.4 or later is now required.

  • Variants that work in both Aura and Lumo themes are now renamed, e.g. ButtonVariant.LUMO_PRIMARY was renamed to ButtonVariant.PRIMARY.

  • In Testbench, methods first() and waitForFirst() are now deprecated and marked for removal. (Vaadin issue)

    • For first(): replacing with single() may not always suffice — consider using id(), making the query context more specific, or using all().getFirst() (especially in tables where multiple elements are expected).

    • For waitForFirst(): replace with single() directly, or use waitUntil with VaadinElementConditions.elementDisplayed.

Vaadin 25.2

  • TreeDataProvider is no longer returned by TreeGrid#getDataProvider(). Tree data must now be accessed via TreeGrid#getTreeData() directly.
    Migration: Replace any cast of TreeGrid#getDataProvider() to TreeDataProvider with a direct call to TreeGrid#getTreeData().

Frontend Changes

  • NotificationUtil info notifications no longer apply the info theme
    Vaadin 25 introduced its own info theme variant for notifications with a visual style that differs from the linkki notification styling. To avoid unintended visual changes, info notifications created by NotificationUtil no longer apply the info theme name. Warning and error notifications are unaffected and continue to use Vaadin’s warning and error theme variants. See Notifications documentation for more information.

  • Stylesheets
    The annotation @Theme is deprecated. Instead, themes are loaded by @StyleSheet.
    For the linkki theme and the F10 theme, a new STYLESHEET constant was added to LinkkiTheme and F10ProductTheme.
    Migration:

    • Replace existing @Theme declarations for linkki or f10-product theme with @StyleSheet(LinkkiTheme.STYLESHEET) or @StyleSheet(F10ProductTheme.STYLESHEET).

    • Make sure that the class that is annotated with StyleSheet is indeed covered by the value of @EnableVaadin.

    • Custom themes should be migrated accordingly:

      • If the custom theme is not reusable, consider moving /themes/mytheme/styles.css to /mytheme/styles.css, which is the location recommended by Vaadin.

      • If the custom theme can be used by downstream projects, and do not need to support usage with @Theme, consider moving /themes/mytheme/styles.css to mytheme/mytheme.css.

    • Consider adjusting the usage of @CssImport: If the annotation is not used to import a style sheet from a npm package, consider importing the stylesheet on AppShellConfigurator directly with @StyleSheet, and move it to src/main/resources/META-INF/resources. Alternatively, consider importing the stylesheet in CSS with @import. This makes it easier to understand which stylesheets are included by having all stylesheets at one place. For more details, see Vaadin documentation.

  • Shadow DOM injection deactivated by default
    Shadow DOM injection is no longer activated by default. All shadow DOM injections in linkki theme are migrated. Migration: For any existing shadow DOM injections, consider migrating them by using :part selector instead. Vaadin documentation provides common CSS selectors for most components, see e.g. documentation for Grid.
    If shadow DOM injection is still needed, the feature flag themeComponentStyles must be set to activate the feature. Note that the property must be declared in the web application module directly.

  • Aura theme
    Vaadin introduces the new Aura theme that coexists with Lumo. Note that the linkki theme does not work with Aura theme at the moment.

  • DOM changes
    Some web components are reworked in this version, most notably overlays (including dialogs). Methods provided by the linkki TestBench extension such as $(OkCancelDialogElement.class) are adjusted accordingly. Other selectors used in UI tests and CSS styling may need to be adjusted.

  • Scrolling in SplitLayouts
    In Vaadin 25, the scrolling behavior of SplitLayout was changed deliberately. Primary and secondary components do not scroll automatically anymore.

    Check all existing usages of SplitLayout if the scrolling behavior is still correct. If the primary and secondary component should scroll, it may be necessary to add overflow: auto to the components. This can be done with LumoUtility.Overflow.AUTO or getStyle().setOverflow(AUTO).
    If the split layout is in a flex container, it may also be necessary to add min-height: 0 to the SplitLayout itself.

  • Styling of Grids changed
    The styling of vaadin-grid elements has changed. This may break custom selectors that apply styling to grids.

Vaadin Release Notes and Migration Guide

For all changes in Vaadin, see Vaadin release notes for Version 25.0.0, Version 25.1.0, Version 25.2.0 as well as the Vaadin 25 migration guide.

Components, UI Annotations and Aspects

  • New components for displaying validation messages
    A new MessagesPanel component is introduced to display a list of messages. It can be used standalone or within the new MessagesSplitLayout, which combines a content component with a collapsible message panel. In MessagesSplitLayout, the message panel is automatically hidden when no messages are present and is shown when messages are available.
    The utility class MessageUiComponents was extended with a method that creates a MessagesPanel that displays the validation messages after validation automatically.
    Another new method handleMessagesAfterValidation can be used with a MessagesSplitLayout to update split position additionally.
    New documentation is added accordingly, see section Message Components.
    Migration:

    • Check existing usages of MessageUiComponents#createMessageTable:

      • If the component should only update after validation, consider using createValidationMessagesPanel instead.

      • If the component does not need any update, consider using MessagesPanel directly.

    • If a custom SplitLayout was used to display validation messages in the secondary component, consider migrating to MessagesSplitLayout (see documentation).

  • New convenience constructor for InfoToolsComponent
    A new constructor InfoToolsComponent(Sequence<T> tools) has been added that opens all tools by default. The existing constructor InfoToolsComponent(Sequence<T> tools, Sequence<T> defaultTools) remains available for cases where only a subset of tools should be open by default.

  • UIBadge
    A new annotation @UIBadge has been added to create badges for displaying visually highlighted information. For more information see UIBadge.

  • Support for additional components in Headlines
    The existing annotation UIHeadline has been extended and can now be used on methods returning either a String or a HeadlinePmo. A HeadlinePmo can be used as return value if additional components should be added to the title or at the end of the headline. These components can be provided as PMOs to the HeadlinePmo.
    Components added using the additional PMOs are updated within the same binding context in which the headline is created.

    Alternatively, HeadlinePmo can also be used directly with VaadinUiCreator to create a Headline.

    For more detailed information, see documentation of UIHeadline.

    For headlines that are created as Vaadin components, a new method addToTitle(Component) can be used to add components directly behind the title.

  • Adding components to the title component of a headline
    Components can now be added directly into the <h2> element using the new method Headline#addToTitle(Component). Components added via this method are preserved when setTitle() is called.

  • UIDateField and UIDateTimeField are no longer created with clear button by default
    In version 2.9.0, UIDateField and UIDateTimeField create components with a clear button by default. This change is reverted based on the common feedback that the clearing of the value triggers unnecessary calculations and validations. To add a clear button to these fields, the new @BindClearButton annotation can be used.

  • @UIMultiSelect: new attribute autoExpand
    The new attribute autoExpand of type MultiSelectComboBox.AutoExpandMode allows configuring the automatic expansion of the field when many chips are selected. The default value is NONE for backwards compatibility.

  • @UIMultiSelect: new attribute selectedItemsOnTop
    The new attribute selectedItemsOnTop can be set to move selected items to the top of the dropdown list. The default value is false for backwards compatibility.

  • BindClearButton
    A new aspect annotation @BindClearButton has been added to set the clear button visible on UI components that implement HasClearButton interface.

  • BindValueChangeMode
    A new annotation @BindValueChangeMode has been added to allow processing the value of a field while still typing, which for example can make search fields more responsive. For more information see BindValueChangeMode

Testing

  • Better support for dialogs in Testbench tests
    Two new methods have been added to VaadinElementConditions: dialogClosed(String title) waits until no dialog with the given title is open and allDialogsClosed() waits until all dialogs are closed. In addition, all methods in OkCancelDialogElement are improved for the case that multiple dialogs are opened.
    Migration: Consider using $(OkCancelDialogElement.class) instead of $(DialogElement.class) wherever applicable.

  • Support for multiple deployments in Testbench tests
    WebDriverExtension now accepts a systemName parameter that scopes all DriverProperties lookups to individual system properties. For example, a WebDriverExtension created with systemName "systemA" reads test.hostname.systemA, test.port.systemA, and test.protocol.systemA instead of the default test.hostname etc. This allows different test classes to target different deployments without interfering with each other.

  • TestBench Extension: better handling of exceptions from WebDriver
    SessionNotCreatedException that can occur during driver creation are now retried. In addition, web drivers in WebDriverExtension are now thread local, which should reduce NoSuchSessionException, improving the stability of parallel UI tests executions.

  • TestBench Extension: support testing for browser alert
    With Chromedriver 126+, chrome driver automatically consumes alerts created during onbeforeUnload which is used in HasBrowserConfiguration when executed in headless mode. This makes it impossible to test these scenarios. In this version, additional options are added to the chrome driver that start with linkki TestBench extension. This makes it possible to test for browser alert again, e.g. using ExpectedCondition.alertIsPresent.

Other Improvements

  • APT validation for @BindClearButton
    The annotation processor now ensures that @BindClearButton is only used with non-primitive return types, as the clear button requires nullable values.

  • Documentation on limitations of unit UI testing with Karibu Documentation was added to make limitations of unit UI testing with Karibu more clear. See section "Limitations of Karibu" in chapter "Unit UI testing with Karibu-Testing".

  • Remove of linkki internal shadow DOM injections
    All internal shadow DOM injections that are used by linkki theme are removed. Shadow DOM injection is deactivated by default in Vaadin 25. If shadow DOM injections are used currently, consider removing them and use selectors such as part instead.
    This change should not cause any visual breaks. If you encounter any unexpected styling or UI test problems, please don’t hesitate to contact us.

  • Removal of deprecated getSectionContent() in LinkkiSection, BaseSection and GridSection
    The method getSectionContent(), deprecated since 2.0.0, has been removed. Use getContentWrapper() instead.

  • ColumnTextAlignAspectDefinition and ColumnSortableAspectDefinition moved to table/column/aspects
    Both classes have been moved from org.linkki.core.ui.table.aspects to org.linkki.core.ui.table.column.aspects as other aspects for table columns are also there.

  • logback-test.xml in linkki-vaadin-flow-testbench-extension no longer affects downstream projects
    The logback-test.xml was packaged into the JAR with root level="TRACE", causing excessive logging in downstream projects. The file has been removed and is no longer included in the JAR. Downstream projects have to provide their own logging configuration now, if required.

Bugfixes

  • linkki-apt validation for all linkki annotations
    linkki-apt can now fully validate usages of all linkki standard annotations.

  • Exceptions for Comboboxes in Grids
    Comboboxes in Grids were causing exceptions during lazy-loading. This was fixed for projects using the application framework. Projects that imported the focus-first scripts for ComboBoxes manually, must remove the @JsModule call to import focus-first-item-combo-box-scroller.js.

Bugfixes

  • TreeGrid in Grid cell did not render content until user interaction
    A Vaadin regression caused TreeGrid components used inside Grid component columns to not display their content after the page loads. Content only appeared after the user interacted with the Grid (e.g. sorting a column). This is fixed by the Vaadin update to 25.2.3.