Upgrading from Vaadin 24

You’ll need to upgrade Spring to the latest versions, including the starter parent dependency:

The Lumo theme is no longer loaded by default, except if you’re using the @Theme annotation to load an application theme folder. If you’re not using @Theme, then add a @StyleSheet annotation to either your application class or a root layout to load the Lumo theme:

All Lumo styles, including badges, but excluding Lumo Utility Classes are included by default when the Lumo theme is loaded. To load the utility classes, add a separate @StyleSheet annotation:

The Material theme is no longer supported in Vaadin 25. You can migrate your application to the Lumo or Aura theme or implement your own Material Design theme on top of the new component base styles.

The un-themed base styles in Vaadin components have changed significantly in Vaadin 25. They are now much less bare-bones and actually provide a better starting point for custom themes. This does mean that custom themes built on top of the Vaadin 25 component base styles need to be heavily refactored. The components’ Styling pages provide lists of style properties (CSS custom properties) that make them easier to customize.

The WebComponentExporter feature in Flow allows you to export Flow components as Web Components for embedding into non-Vaadin user interfaces. In Vaadin 25, stylesheets loaded into exported components using the @CssImport annotation only load those styles into the exported component’s shadow DOM, not the surrounding page as before. To load the same styles into the surrounding page, import the stylesheet to it separately.

The Lumo CSS files have been removed from the @vaadin/react-components package. As mentioned above, the Lumo theme should be imported from @vaadin/vaadin-lumo-styles instead.

One exception is the @vaadin/react-components/css/lumo/Utility.module.css CSS module, which has been preserved for backward compatibility as the Lumo package does not expose utilities as a CSS module.

These changes are optional, as old approaches still work (with the exceptions listed in the Breaking Changes section), but recommended to get your application to the new best practices in Vaadin 25, and to avoid breaking changes in later major versions.

The bottom attribute was removed and can no longer be used to target the bottom navbar. Instead, use the selector ::part(navbar-bottom) to target it with CSS.

The Cookie Consent component has been removed. Vaadin does not provide any replacement, but several third party options exist, such as orestbida/cookieconsent.

The Flow ConfirmDialog now only implements HasComponents instead of HasOrderedComponents. The following methods are not available anymore: replace, indexOf, getComponentCount, getComponentAt, getChildren.

Methods that allowed passing an Element instance have been removed. Use the corresponding alternatives that allow passing a Component instance instead.

The add method has been removed from the Flow ContextMenu. Instead, use addItem to add menu items, or addComponent to add generic components without wrapping them into a menu item.

The “New Item” button in the CRUD component no longer uses the primary style variant by default. To get the old default back:

The setWidthAdjust / getWidthAdjust methods of the Title class have been removed because it was removed from the underlying Highcharts library.

The DrillUpButton class has been removed from the codebase and all of its related API, e.g., setDrillUpButton / getDrillUpButton from the Drilldown class. Use Breadcrumbs instead. Likewise, the setDrillUpText / getDrillUpText has been removed from the Lang class.

All methods that accept Date as parameter that were previously marked as deprecated have been removed.

Chart configurations are now serialized using Jackson 3. The ChartSerialization.setObjectMapperInstance method that can be used to customize serialization behavior now expects a tools.jackson.databind.ObjectWriter instance.

The following changes have been made to the internal DOM structure of the Date Picker overlay, which may affect custom styling:

In the Flow DateTimePicker component, validation is no longer triggered on blur if the value has remained unchanged after user interaction, making this behavior consistent with the rest of the field components, which already received a similar update in V24.

Incomplete input, where only a date or only a time is entered, is now treated as invalid. The corresponding error message can be configured via DateTimePickerI18n:

The setContent and addContent methods have been removed from the Flow Details component. Use regular methods from HasComponents such as add, remove, removeAll instead.

Dialog and ConfirmDialog do not show a closing animation anymore when removing the component from the UI / DOM. Instead, the dialog should be closed and the closed event needs to be used to wait for the closing animation to finish before removing the component.

For Flow this is relevant when manually adding / removing the dialog from the UI. The event is not needed when calling dialog.open() without adding the dialog to the UI.

For Hilla / React this is relevant when rendering dialogs conditionally.

The following custom CSS properties have been removed from vaadin-form-item:

Use the following CSS properties on vaadin-form-layout instead:

The Map component’s borderless / BORDERLESS style variant has been renamed no-border / NO_BORDER for consistency with other components.

The TestBench API MenuBarElement.OVERLAY_TAG has been removed. To get a reference to a sub-menu, instead use MenuBarButtonElement.openSubMenu which returns a reference.

The send button no longer uses the Primary style variant by default. To revert this change you can style the button with CSS:

Also, the send button now is a vaadin-message-input-button instead of vaadin-button.

The Multi-Select Combo Box no longer uses vaadin-multi-select-combo-box-internal internally. This may affect custom shadow DOM styling of the component.

Component overlays (like Dialog or the Combo Box drop-down) are no longer rendered outside of the component itself. This causes the following breaking changes to overlay styling:

You’ll find the appropriate selector in the component’s Styling page.

The Lit/React component’s contentWidth and contentHeight properties have been replaced by width and height.

The on attribute was removed and can no longer be used to target toggled-on buttons. Instead, use the selector ::part(toolbar-button-pressed) to target them with CSS.

The Split Layout component no longer sets overflow:auto on its two child elements. The Scroller component is recommended to make them scrollable on overflow. Alternatively, you can apply it manually with CSS:

The SplitterDragendEvent and addSplitterDragendListener have been renamed to SplitterDragEndEvent and addSplitterDragEndListener, respectively.

The TabsVariant.LUMO_ICON_ON_TOP and TabSheetVariant.LUMO_ICON_ON_TOP theme variants have been removed. Apply the TabVariant.LUMO_ICON_ON_TOP to individual tabs instead.

The HasPrefixAndSuffix interface has been removed from the Flow TextField and related components. The components now implement HasPrefix and HasSuffix instead.

The Time Picker no longer uses vaadin-time-picker-combo-box internally. This may affect custom shadow DOM styling of the component.

The TimePickerOverlayElement TestBench element has been removed as the component now uses the native HTML popover mechanism for its drop-down. The getItem and getLastItem methods are now available on TimePickerElement itself.

Tree Grid’s client-side approach to data loading has been refactored. Instead of requesting data for each hierarchy level separately, it now sends a single request for the visible range, and the server returns the corresponding items as a flat list. On the server side, in turn, it’s now possible to choose how the data provider returns hierarchical data: HierarchyFormat.NESTED (default, each expanded level separately) or HierarchyFormat.FLATTENED (all expanded levels as a flat list). These updates introduce breaking changes, which are described below.

The pageSize property now applies to the entire flattened hierarchy rather than to each level individually as before.

Expanded items are no longer exposed to the client side as a plain array. Instead, the web component receives depth information for each item and uses it to display the data as a tree structure.

As a result, the TreeGridElement#isLoadingExpandedRows TestBench API has been removed. You no longer need to wait for expanded rows specifically since they are loaded in the same request with other rows.

The TreeGridElement#getNumberOfExpandedRows TestBench API has also been removed. Use unit tests instead to verify that exact items are expanded:

The following section is relevant if your code extends Grid or TreeGrid, or accesses low-level Flow APIs like HierarchicalDataCommunicator.

Tree Grid now supports scrolling to a specific item using scrollToItem(T). Unlike scrollToIndex(int…​), this method automatically expands any collapsed parent items before scrolling to the target item.

This feature relies on the getParent(T) and getItemIndex(T, HierarchicalQuery) methods of the HierarchicalDataProvider interface. To use scrollToItem(T), your data provider must implement these methods. The built-in TreeDataProvider already provides full support out of the box.

The following table shows which methods need to be implemented, depending on the data provider type and whether it is in-memory or not:

The vaadin-upload-file elements representing files in the list now use CSS grid layout instead of flexbox. This may affect custom styling of the element.

The row and info parts have been removed from the vaadin-upload-file element.

Flow components using validation do not implement HasClientValidation anymore, as such the addClientValidatedEventListener method has been removed. Consider using ValidationStatusChangeEvent to get notified when users enter input that can not be parsed.

URLs not explicitly specified in security configuration changed from being allowed for authenticated users to restricted by default. This requires extra security rules (path matchers) for URLs that were allowed only for authentication users.

Vaadin Flow layouts now require access annotation (e.g. RolesAllowed) on layout classes. This was added to align with auto-layout default security rules.