> Markdown version of [Vaadin 14 to 23 Upgrade Instructions](https://vaadin.com/docs/v23/upgrading/essential-steps). Section index: [llms.txt](https://vaadin.com/docs/v23/upgrading/llms.txt)

# Vaadin 14 to 23 Upgrade Instructions

This is a list of the changes you need to make in your application when upgrading it from Vaadin 14 to Vaadin 23, so that it compiles, runs, behaves and looks the way it did in Vaadin 14.

Some of these instructions are only necessary if you are using certain features (such as templates or Spring security) or applying certain techniques (such as custom styling of Vaadin components).

The [Recommended Changes](https://vaadin.com/docs/v23/upgrading/recommended-changes.md) page lists further changes that, although they aren’t essential, are recommended to conform with Vaadin 23 best practices and to avoid using deprecated APIs and features.

## <a id="upgrading-from-other-versions"></a>Upgrading from Other Versions

- Upgrading from an intermediate version (for example, V20)? Use the [Upgrade Guide Generator](https://vaadin.com/docs/v23/upgrading/upgrade-tool.md) to generate step-by-step instructions from that version.

- Upgrading from a version before Vaadin 14? Follow [the older guides](/docs/v14/flow/upgrading) to upgrade to V14 first, and then continue with this guide.

- You can also use components and views developed with Vaadin 7 or 8 inside an application written for the latest version by using [Multiplatform Runtime](https://vaadin.com/docs/v23/tools/mpr/overview.md).

> **Note: Before You Start**
>
> - Check the list of [minimum requirements and supported technologies](https://github.com/vaadin/platform/releases/tag/23.0.0) for Vaadin 23 to ensure that it conforms with your own requirements.
>
> - Check the compatibility of the [add-ons](https://vaadin.com/directory/) you’re using to see if they work with Vaadin 23.
>
> - If for any reason you need to downgrade to an earlier Vaadin version, make sure to clean generated resources by using Maven or Gradle clean functionality: `mvn vaadin:clean-frontend` or `gradle vaadinClean`. Check the [documentation](https://vaadin.com/docs/v23/production/production-build.md#clean-frontend) to see what is removed by the command.

## <a id="preliminary-steps"></a>Preliminary Steps

- Delete the `node_modules` folder and lock file – either `package-lock.json` with `npm` or `pnpm-lock.yaml` with `pnpm`.

- Edit the `pom.xml` file and change the Vaadin version to the latest-available Vaadin 23 version.

## <a id="update-to-java-11"></a>Update to Java 11+

- The Java version requirement has changed from Java 8 to Java 11 or greater — Java 17 is also supported.

  For Maven, update `java.version`:

  ```xml
  <properties>
      <java.version>11</java.version>
  </properties>
  ```

  Or `compiler.source` and `compiler.target`:

  ```xml
  <properties>
      <maven.compiler.source>11</maven.compiler.source>
      <maven.compiler.target>11</maven.compiler.target>
  </properties>
  ```

- If the `maven-failsafe-plugin` version is explicitly set in your project, ensure the version is set to `2.21.0` or higher for the plugin to be [compatible with Java 9+](https://maven.apache.org/surefire/maven-failsafe-plugin/java9.html).

## <a id="update-spring-settings"></a>Update Spring Settings

Spring has various settings you may need to update. They’re listed in the sections below.

### <a id="update-spring-version"></a>Update Spring Version

Vaadin is compatible with Spring 5.3.18 or later, and Spring Boot 2.7 or later. If your application uses an older version of Spring, though, update it to a compatible version:

`pom.xml`

```xml
<parent>
    <groupId>org.springframework.boot</groupId>
    <artifactId>spring-boot-starter-parent</artifactId>
    <version>2.7.1</version>
</parent>
```

Upgrading the Spring version might require some non-Vaadin-related changes to your application. See the [Spring Boot release notes](https://github.com/spring-projects/spring-boot/wiki) for the list of required changes.

> **Note: Cyclic Dependency in Bakery Starter**
>
> If your project is based on the [V14 Bakery starter](/docs/v14/flow/starters/bakeryflow) and you encounter an error due to cyclic dependencies after updating the Spring version, it could be the result of having an `@Autowired` field of type `PasswordEncoder` and a method that provides the bean for the same type in the `SecurityConfiguration` class.
>
> Fix this by moving them to separate classes or, preferably, remove the field in favor of using [Vaadin Spring Security helpers](https://vaadin.com/docs/v23/security/enabling-security.md).

### <a id="update-spring-security"></a>Update Spring Security

If your application uses Spring security, ensure that the `offline-stub.html` and `sw-runtime-resources-precache.js` files are added to the list of static resources that are allowed to bypass Spring security. This can be done by providing a `SecurityFilterChain` bean similar to the following:

```java
@Bean
public SecurityFilterChain filterChain(HttpSecurity http) throws Exception {
    http.authorizeRequests().antMatchers(
        ...

        "/offline-stub.html",
        "/sw-runtime-resources-precache.js",

        ...
    ).permitAll();
    return http.build();
}
```

## <a id="enable-server-side-bootstrapping"></a>Enable Server-Side Bootstrapping

Vaadin 23 uses a client-side bootstrapping approach that’s different from the server-side mode that’s used in Vaadin 14. This change requires some alteration to your Vaadin 14 codebase. However, to expedite migrating your application to Vaadin 23, you can enable Vaadin 14 server-side bootstrapping using the `useDeprecatedV14Bootstrapping` flag.

This guide describe the code changes required to use the new bootstrapping mode in a later section. To do this in a Spring project, you can add the following to `application.properties`:

`application.properties`

```
vaadin.useDeprecatedV14Bootstrapping=true
```

Alternatively, if you have a plain Java project, you can enable `useDeprecatedV14Bootstrapping` by adjusting the `vaadin-maven-plugin` configuration in `pom.xml` as follows:

`pom.xml`

```
<plugin>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-maven-plugin</artifactId>
    <configuration>
        <useDeprecatedV14Bootstrapping>true</useDeprecatedV14Bootstrapping>
    </configuration>
</plugin>
```

To migrate the deprecated server-side bootstrapping to the modern client-side bootstrapping, see the [required Bootstrapping Changes](https://vaadin.com/docs/v23/upgrading/recommended-changes.md#bootstrapping-changes) section.

## <a id="changed-apis"></a>Changed APIs

A set of breaking API changes and their replacements are listed below:

- `AbstractListDataView` now requires an extra constructor argument – a callback which is invoked each time the component’s filter or sorting changes through the data view API.

- Property synchronization methods in `Element` are replaced by a similar API in `DomListenerRegistration`: `getSynchronizedPropertyEvents()`, `getSynchronizedProperties()`, `removeSynchronizedPropertyEvent()`, `removeSynchronizedProperty()`, `addSynchronizedPropertyEvent()`, `addSynchronizedProperty()`, and `synchronizeProperty()`.

- The methods `JsModule#loadMode()` and `Page#addJsModule(String, LoadMode)`, which were used to set the load mode of JsModule, have been removed since they don’t work with JavaScript modules.

- The construction methods `BeforeEvent(NavigationEvent, Class<?>)` and `BeforeEvent(Router, NavigationTrigger, Location, Class<?>, UI)` in `BeforeEvent` are replaced by `BeforeEvent(NavigationEvent, Class, List)` and `BeforeEvent(Router, NavigationTrigger, Location, Class, UI, List)`.

- The methods `getUrl()`, `getUrlBase()` and `getRoutes()` in `Router` are replaced by the methods `getUrl()`, `getUrlBase()` and `getAvailableRoutes()` in `RouterConfiguration`. The `resolve()` method in `Router` is replaced by the `resolve()` method in `RouteUtil`. The `getRoutesByParent()` method in `Router` is removed and has no replacement.

- `ServletHelper` is replaced by `HandlerHelper`.

- The `getBodyAttributes()` method in `AbstractTheme`, `Lumo` and `Material` is replaced by `getHtmlAttributes()`.

- The `removeDataGenerator()` method in `HasDataGenerators` and `CompositeDataGenerator` is removed in favor of using the registration returned from `addDataGenerator(DataGenerator)`.

- The methods `preventsDefault()` and `stopsPropagation()` in `ShortcutRegistration` are replaced by `isBrowserDefaultAllowed()` and `isEventPropagationAllowed()`.

- The `safeEscapeForHtml()` method in `VaadinServlet` is removed in favor of using `org.jsoup.nodes.Entities#escape(String)`.

- The static method `getInstance()` in `ApplicationRouteRegistry` is removed in favor of the instance method.

- The `enableInstallPrompt()` parameter of the `@PWA` annotation has been removed without a replacement. See this [GitHub issue](https://github.com/vaadin/flow/issues/8038) to understand the motive for this removal.

- The protected instance method `getApplicationUrl()` from `VaadinServlet` is removed.

- The `HasOrderedComponents`, `HasEnabled`, `HasValidation` and `HasText` interfaces are no longer generic. Therefore, type parameters should be removed.

- The constructor `PlotLine(Number value)` in Charts no longer exists. Use the no-arg constructor and then set the value explicitly with `setValue(Number value)` method, instead.

- The `ComboBox` has new constructor overloads that prevent `new ComboBox<>(null)` from compiling. Instead, use a cast for the null value so that the correct constructor can be identified (e.g., `new ComboBox<>((String) null)`).

- The `@Theme` annotation now takes a [theme folder](https://vaadin.com/docs/v23/upgrading/recommended-changes.md#custom-theme-folder) name as its `value` parameter. Use the `themeClass` parameter to specify a theme class instead:

  ```java
  @Theme(Material.class)
  ```

  ```java
  @Theme(themeClass = Material.class)
  ```

  Correspondingly, combined with a theme variant:

  ```java
  @Theme(value = Lumo.class, variant = Lumo.DARK)
  ```

  ```java
  @Theme(themeClass = Lumo.class, variant = Lumo.DARK)
  ```

## <a id="miscellaneous-changes"></a>Miscellaneous Changes

The following features have changes in their behavior, although their APIs are unchanged.

- If necessary, add a `router-ignore` attribute to the anchor elements whose navigation should bypass the Vaadin router. This is needed, for example, if an anchor is used to log users out in Spring Security. Without the `router-ignore` attribute, the Vaadin router intercepts the navigation to `/logout`, preventing Spring Security from handling logout as intended. To fix this, add the `router-ignore` attribute as in the following example:

  ```java
  Anchor logoutLink = new Anchor("/logout", "Logout from app");
  logoutLink.getElement().setAttribute("router-ignore", true);
  ```

- The [server-side modality mechanism](https://vaadin.com/docs/v23/advanced/server-side-modality.md) introduced in V23 changes the behavior of modal Dialogs. Opening another Dialog when a modal Dialog is already open automatically makes the new Dialog a child of the previously opened one. Closing the "parent" modal also closes all subsequently opened Dialogs. To keep other Dialogs open when closing a modal Dialog, add them to the UI explicitly before opening:

  ```java
  Dialog firstDialog = new Dialog(new Span("First"));
  Dialog secondDialog = new Dialog(new Span("Second"));

  // Add dialogs explicitly to UI
  add(firstDialog, secondDialog);

  // Later open dialogs
  firstDialog.open();
  secondDialog.open();
  ```

- Positive `tabindex` values (e.g., `setTabIndex(5)`) are no longer supported on input fields. Doing this doesn’t cause errors, but it also doesn’t have any effect on the tab order. However, `tabindex` values of `0` (i.e., to add a tab stop) and `-1` (i.e., to remove a tab stop) are still supported. It’s recommended to ensure that input fields are in the correct order in the DOM, instead of overriding the tab order with `setTabIndex()`.

- The DOM structure of many components has changed since V14. While this has no effect on their regular Java APIs, code that utilizes Flow’s Element API to access a component’s internal elements may be affected.

- For Vaadin Charts, if `XAxis` or `YAxis` is added to a chart, the ticks of those axes are now hidden by default. To display the ticks, provide the axes with a tick width greater than 0 using `XAxis.setTickWidth()` and `YAxis.setTickWidth()`.

- In V23.1 and later, required indicators on input fields are no longer hidden when the field has a value. The old behavior — which required field shown only when the field is empty — can be brought back using the following (global) CSS:

  `styles.css`

  ```css
  [required][has-value]::part(required-indicator)::after {
    opacity: 0;
  }
  ```

- In V14, when doing non-router navigation — i.e., via direct link or an `Anchor` within the application — to a specific route, the return value of `VaadinRequest.getPathInfo()` includes the route portion of the path. In V23, a `/` without the route part is always returned for such requests. This causes cookies set using route-specific paths not to work correctly. A workaround, to achieve functionality similar to V14, is to set the `eagerServerLoad` configuration parameter to `true`. See [properties](https://vaadin.com/docs/v23/configuration/properties.md#properties) for more information.

## <a id="update-selenium-version"></a>Update Selenium Version

If your application is based on the `spring-boot-starter-parent` and you use Vaadin TestBench to run integration tests, you’ll need to update the `selenium.version` property in the `pom.xml` file to `4.X`. This is to override the outdated Selenium version that gets inherited from the Spring Boot parent.

`pom.xml`

```xml
<properties>
    <!-- Overrides the old version specified by the Spring Boot parent -->
    <selenium.version>4.1.2</selenium.version>
</properties>
```

## <a id="update-your-css"></a>Update Your CSS

Click and read if you have styled Vaadin components.

### <a id="styling-input-field-components"></a>Input Field Components

These changes apply to all input field components, except Checkbox. See the sections for individual components for details and other component-specific changes.

#### <a id="input-fields-no-longer-inherit-text-field-styles"></a>Input Fields No Longer Inherit Text Field Styles

The following components *used to* be based on the Text Field component, so styles applied to Text Field were automatically applied to them,too:

- Combo Box

- Date Picker

- Number Field and Integer Field

- Select

- Time Picker

`vaadin-text-field.css`

```css
/* This used to apply to all of the above components */
[part="input-field"] {
  border: 1px solid gray;
}
```

This is no longer the case, so any styles shared between these components need to be applied to each of them separately. To avoid duplicating CSS, you can place all styles shared between input field components in a separate style sheet, as follows:

`input-fields-shared-styles.css`

```css
[part="input-field"] {
  border: 1px solid gray;
}
```

These styles can then be applied to each component by importing the shared style sheet into each component-specific style sheet:

`components/vaadin-combo-box.css`

```css
@import '../input-fields-shared-styles.css';
```

#### <a id="labels"></a>Labels

Labels have been changed to slotted child elements. Although the `[part="label"]` selector still works, some derived selectors may need to be adjusted.

The `:empty` selector no longer works correctly to distinguish empty and non-empty labels, and should be replaced by the `[has-label]` attribute selector:

```css
[part="label"]:not(:empty) {...}
```

```css
:host([has-label]) [part="label"] {...}
/* Or, to target the slotted element itself */
:host([has-label]) ::slotted(label) {...}
```

Setting an input field’s label in Flow no longer generates a `label` attribute on the component’s root element. Selectors that use it need to be rewritten to use the `has-label` attribute instead:

```css
:host([label]) {...}
```

```css
:host([has-label]) {...}
```

#### <a id="error-messages"></a>Error Messages

Error messages have been changed to slotted child elements. Although the `[part="error-message"]` selector still works, some derived selectors may need to be adjusted. The `:empty` selector no longer works correctly on these and should be replaced by attribute selectors for the appropriate states:

```css
[part="error-message"]:not(:empty) {...}
```

```css
[has-error-message] [part="error-message"] {...}
```

#### <a id="required-indicators"></a>Required Indicators

Required indicators now have their own shadow parts, instead of being pseudo-element children of the `label` part:

```css
[part="label"]::after {...}
```

```css
[part="required-indicator"]::after {...}
```

#### <a id="default-text-field-width"></a>Default Text Field Width

The CSS property that defines the default width of text input fields has been renamed to `vaadin-field-default-width`:

```css
html {
  --vaadin-text-field-default-width: 20em;
}
```

```css
html {
  --vaadin-field-default-width: 20em;
}
```

### <a id="button"></a>Button

#### <a id="disabled-button-styles"></a>Disabled Button Styles

The styling of disabled buttons has changed from reduced opacity to grayscale coloring, which may affect custom styling of buttons. Secondary and tertiary buttons now use `--lumo-disabled-text-color` for text, and primary buttons use `--lumo-contrast-30pct` for background and `--lumo-base-color` for text.

#### <a id="styles-inherited-by-select-v23-0-only"></a>Styles Inherited by Select (V23.0 Only)

The [Select](#select) component has been refactored to use an internal button which, in V23.0, inherits styles applied to the Button component. To get rid of unwanted Button styles in Select, you need to either override them or scope Button styles to apply only to actual Buttons by specifying the element name in their selectors:

`vaadin-button.css`

```css
:host {...}
:host([theme~="primary"]) {...}
```

`vaadin-button.css`

```css
:host(vaadin-button) {...}
:host(vaadin-button[theme~="primary"]) {...}
```

In V23.1, [Select](#select) has been changed so that it no longer inherits Button styles.

### <a id="charts"></a>Charts

#### <a id="switch-to-css-styling-mode"></a>Switch to CSS Styling Mode

Vaadin Charts now defaults to Java styling mode in Flow, instead of CSS styling mode. If you have applied custom styles to charts using CSS, you need to make the following change to switch your charts back to CSS styling mode:

```java
Chart chart = new Chart();
Configuration conf = chart.getConfiguration();
conf.getChart().setStyledMode(true);
```

#### <a id="remove-references-to-old-default-theme"></a>Remove References to Old Default Theme

The old `vaadin-charts-default-theme` style module no longer exists, so it needs to be removed from `@CssImport`

```java
@CssImport(value="my-charts-styles.css", themeFor="vaadin-chart", include="vaadin-chart-default-theme")
```

```java
@CssImport(value="my-charts-styles.css", themeFor="vaadin-chart")
```

(Correspondingly, if you have used a JS module for your custom chart styles, you need to remove the import of the default theme, as well as its `include`, in the `<style>` element. It’s also recommended to refactor the module into a regular style sheet.)

#### <a id="new-default-themes"></a>New Default Themes

The default colors in charts have changed in Vaadin 23 to match the Lumo and Material themes better. You can revert to the old color scheme by switching to CSS styling mode and applying the `classic` theme:

```java
chart.getElement().setAttribute("theme", "classic");
```

### <a id="checkbox-and-radio-button"></a>Checkbox and Radio Button

#### <a id="label"></a>Label

Unlike most input field components, Checkboxes and Radio Buttons no longer have a `label` shadow part, so the label must be targeted as a child element:

```css
[part="label"] {...}
```

```css
::slotted(label) {...}
```

#### <a id="lumo-properties-instead-of-inherited-styles"></a>Lumo Properties Instead of Inherited Styles

Checkbox and Radio Button now use Lumo properties for all colors and fonts, instead of inheriting some of these from their parent elements, and base all their dimensions on Lumo properties instead of basing them on the current font size:

- Label color: `--lumo-body-text-color`

- Label font size: `--lumo-font-size-m`

- Label line-height: `--lumo-line-height-s`

- Label margins: `--lumo-space-s` and `lumo-space-xs`

- Checkbox / Radio Button width & height: `--lumo-size-m`

- Checkbox / Radio Button margins: `--space-xs`

### <a id="checkbox-group"></a>Checkbox Group

See changes common to all [input field components](#styling-input-field-components).

### <a id="combo-box"></a>Combo Box

- No longer inherits Text Field styles.

- See changes common to all [input field components](#styling-input-field-components).

- See changes to [Text Field](#styling-text-field), as these also apply to Combo Box.

#### <a id="styles-no-longer-inherited-from-text-field"></a>Styles No Longer Inherited from Text Field

This component is no longer based on Text Field, so all styles previously applied via Text Field need to be applied to it separately in one of the following ways:

- Using a theme folder, place the styles in `/components/vaadin-combo-box.css`

- Or, in Flow, with `@CssImport(…​, themeFor="vaadin-combo-box")`

#### <a id="overlay-and-list-items"></a>Overlay and List Items

The contents of `vaadin-combo-box-item` are now slotted child elements. This mainly affects styles applied to custom renderers:

```css
[content].some-classname {...}
```

```css
::slotted(.some-classname) {...}
```

The selection checkmarks in them have been moved to their own shadow parts:

```css
:host::before {...}
```

```css
[part="checkmark"]::before {...}
```

#### <a id="miscellaneous"></a>Miscellaneous

The `vaadin-text-field-container` internal wrapper has been renamed `vaadin-combo-box-container`. *(Note: this is an internal element whose styling isn’t supported)*.

### <a id="confirm-dialog"></a>Confirm Dialog

Styles should now target the `vaadin-confirm-dialog-overlay` element instead of `vaadin-confirm-dialog`.

### <a id="crud"></a>CRUD

Depending on the editor position, styles for the CRUD editor should now target either the `vaadin-crud` element itself (for *aside* and *bottom* positions) or `vaadin-crud-dialog-overlay` (for the *overlay* position), instead of `vaadin-dialog-layout`.

### <a id="date-picker"></a>Date Picker

- No longer inherits Text Field styles.

- See changes common to all [input field components](#styling-input-field-components).

- See changes to [Text Field](#styling-text-field), as these also apply to Date Picker.

#### <a id="styles-no-longer-inherited-from-text-field-2"></a>Styles No Longer Inherited from Text Field

This component is no longer based on Text Field, so all styles previously applied via Text Field need to be applied to it separately in one of the following ways:

- Using a theme folder, place the styles in `/components/vaadin-date-picker.css`

- Or, in Flow, with `@CssImport(…​, themeFor="vaadin-date-picker")`

#### <a id="miscellaneous-2"></a>Miscellaneous

- The `vaadin-text-field-container` internal wrapper has been renamed `vaadin-date-picker-container`. *(Note: this is an internal element whose styling isn’t supported).*

- The calendar overlay’s week number text color has changed from `--lumo-tertiary-text-color` to `--lumo-secondary-text-color`.

### <a id="date-time-picker"></a>Date Time Picker

- See changes common to all [input field components](#styling-input-field-components).

- See changes to [Text Field](#styling-text-field), as these also apply to Date Time Picker.

#### <a id="styles-no-longer-inherited-from-custom-field"></a>Styles No Longer Inherited from Custom Field

This component is no longer based on Custom Field, so all styles previously applied via Custom Field need to be applied to Date Time Picker separately in one of the following ways:

- Using a theme folder, place the styles in `/components/vaadin-date-time-picker.css`

- Or, in Flow, with `@CssImport(…​, themeFor="vaadin-date-time-picker")`

#### <a id="slotted-date-picker-and-time-picker"></a>Slotted Date Picker and Time Picker

The Date Picker and Time Picker sub-fields are now slotted children of the Date Time Picker:

```css
[part="date"] {...}
[part="time"] {...}
```

```css
::slotted([slot="date-picker"]) {...}
::slotted([slot="time-picker"]) {...}
```

The internal `slot-container` wrapper has been renamed `slots`. *(Note: this is an internal element whose styling isn’t supported).*

### <a id="grid"></a>Grid

The color and opacity of inactive sort indicators have been changed from `--lumo-body-text-color` at 0.2 opacity (0.6 on hover) to `--lumo-tertiary-text-color` (`--lumo-body-text-color` on hover) at 1.0 opacity.

### <a id="horizontal-and-vertical-layout"></a>Horizontal and Vertical Layout

Vertical Layout and Horizontal Layout have been refactored to use the CSS `gap` property for spacing between components, instead of margins. This makes it possible to use `flex-wrap` to wrap the contents of these layouts without spacing conflicts. Custom margins applied to components in these layouts are now applied *in addition to* the spacing, instead of *overriding* the spacing. Although the best approach is to refactor all custom margins applied to elements inside layouts with spacing, a quick fix is to subtract `var(--lumo-space-m)` from affected margins (`margin-top` for Vertical Layouts and `margin-left` for Horizontal Layouts):

```css
.some-layout-child {
  margin-left: 50px;
}
```

```css
.some-layout-child {
  margin-left: calc(50px - var(--lumo-space-m));
}
```

### <a id="icons"></a>Icons

Icons are now rendered as `vaadin-icon` elements instead of `iron-icon`.

```css
::slotted(iron-icon) {...}
```

```css
::slotted(vaadin-icon) {...}
```

### <a id="number-field-and-integer-field"></a>Number Field and Integer Field

- No longer inherit Text Field styles.

- See changes common to all [input field components](#styling-input-field-components).

- See changes to [Text Field](#styling-text-field), as these also apply to Number Field and Integer Field.

#### <a id="styles-no-longer-inherited-from-text-field-3"></a>Styles No Longer Inherited from Text Field

This component is no longer based on Text Field, so all styles previously applied via Text Field need to be applied to it separately in one of the following ways:

- Using a theme folder, place the styles in `/components/vaadin-number-field.css`

- Or, in Flow, with `@CssImport(…​, themeFor="vaadin-number-field")`

### <a id="password-field"></a>Password Field

All styles are still inherited from [Text Field](#styling-text-field), so the same changes apply to it.

### <a id="radio-button-group"></a>Radio Button Group

- See changes common to all [input field components](#styling-input-field-components).

- See [Checkbox and Radio Button](#checkbox-and-radio-button) for changes to Radio Button.

### <a id="select"></a>Select

- See changes common to all [input field components](#styling-input-field-components).

- In V23.0, Select inherits styles from Button. See [Button](#button) upgrade instructions for details on how to work around it. (This is no longer the case in V23.1.)

#### <a id="styles-no-longer-inherited-from-text-field-4"></a>Styles No Longer Inherited from Text Field

This component is no longer based on Text Field, so all styles previously applied via Text Field need to be applied to it separately in one of the following ways:

- Using a theme folder, place the styles in `/components/vaadin-select.css`

- Or, in Flow, with `@CssImport(…​, themeFor="vaadin-select")`

#### <a id="new-list-item-element"></a>New List Item Element

List items are now `vaadin-select-item` elements instead of `vaadin-item` (although they extend the latter, so styles applied to `vaadin-item` apply to `vaadin-select-item` as well).

`styles.css`

```css
vaadin-select-overlay vaadin-item {...}
```

`styles.css`

```css
vaadin-select-item {...}
```

The contents of `vaadin-select-item` are slotted child elements. This mainly affects styles applied to custom renderers:

```css
[content].some-classname {...}
```

```css
::slotted(.some-classname) {...}
```

#### <a id="selection-checkmarks"></a>Selection Checkmarks

The selection checkmarks in these have been moved to their own shadow parts:

```css
:host::before {...}
```

```css
[part="checkmark"]::before {...}
```

#### <a id="value-displayed-in-field"></a>Value Displayed in Field

The value displayed in the field uses the new item element, too. It’s now a child of a new `vaadin-select-value-button` internal component, and is easiest to access as a regular child element of Select:

```css
[part="value"] vaadin-item {...}
```

`styles.css`

```css
vaadin-select vaadin-select-item {...}
```

#### <a id="placeholder-text"></a>Placeholder Text

The value placeholder text needs to be targeted a bit differently from other similar fields:

```css
[part="value"]:placeholder-shown {...}
```

```css
::slotted([placeholder]) {...}
```

### <a id="tabs"></a>Tabs

The color of inactive tabs has been changed from `--lumo-contrast-60pct` to `--lumo-secondary-text-color`.

### <a id="text-area"></a>Text Area

See changes common to all [input field components](#styling-input-field-components).

#### <a id="slotted-native-input-element"></a>Slotted Native Input Element

The native `<textarea>` element is now a slotted child element, and the value shadow part has been removed:

```css
[part="value"] {...}
```

```css
::slotted(textarea) {...}
```

This also affects selectors for the placeholder text:

```css
[part="value"]::placeholder {...}
/* or */
[part="value"]:placeholder-shown {...}
```

```css
::slotted(textarea:placeholder-shown) {...}
```

### <a id="styling-text-field"></a>Text Field

See changes common to all [input field components](#styling-input-field-components).

#### <a id="other-components-no-longer-inherit-text-field-styles"></a>Other Components No Longer Inherit Text Field Styles

The following components no longer inherit styles applied to Text Field, and need to be styled separately. See [input field components](#styling-input-field-components) for details.

- Combo Box

- Date Picker

- Number Field and Integer Field

- Select

- Time Picker

However, the same structural changes have been made to these as to Text Field, so the following changes and corresponding instructions apply to them as well.

#### <a id="slotted-native-input-element-2"></a>Slotted Native Input Element

The native `<input>` element is now a slotted child element, and the value shadow part has been removed:

```css
[part="value"] {...}
```

```css
::slotted(input) {...}
```

This also affects selectors for the placeholder text:

```css
[part="value"]::placeholder {...}
/* or */
[part="value"]:placeholder-shown {...}
```

```css
::slotted(input:placeholder-shown) {...}
```

#### <a id="placeholder-text-color"></a>Placeholder Text Color

Placeholder text now uses the `--lumo-secondary-text-color` color property, instead of `--lumo-body-text-color` with 0.5 opacity.

### <a id="time-picker"></a>Time Picker

- No longer inherits Text Field styles.

- See changes common to all [input field components](#styling-input-field-components).

- See changes to [Text Field](#styling-text-field), as these also apply to Number Field and Integer Field.

#### <a id="styles-no-longer-inherited-from-text-field-5"></a>Styles No Longer Inherited from Text Field

This component is no longer based on Text Field, so all styles previously applied via Text Field need to be applied to it separately in one of the following ways:

- Using a theme folder, place the styles in `/components/vaadin-time-picker.css`

- Or, in Flow, with `@CssImport(…​, themeFor="vaadin-time-picker")`

### <a id="upload"></a>Upload

The `clear-button` part has been renamed `remove-button`:

```css
[part="clear-button"] {...}
```

```css
[part="remove-button"] {...}
```

### <a id="loading-indicator"></a>Loading Indicator

The loading indicator (the flashing blue bar at the top of the page) has been replaced in Vaadin 23 with a new component called the connection indicator, which has four states: connected, loading, connection lost, reconnecting. Custom themes applied to the loading indicator still work in Vaadin 23 (as they apply to the loading state of the new indicator). However, for the other states (that is, for the connected, connection lost, and reconnecting states) there is currently a [bug](https://github.com/vaadin/flow/issues/12696) that causes the connection indicator in these states to always be visible at the bottom of every screen (as plain text of the connection status such as "Online"). As a workaround, you can copy the [default styles of the connection indicator](https://github.com/vaadin/flow-hilla-common/blob/main/frontend/packages/common-frontend/src/ConnectionIndicator.ts#L284) into a style sheet in your project, and add the desired loading indicator styles on top of those.

## <a id="update-your-templates"></a>Update Your Templates

Click and read if you are using Lit templates.

### <a id="the-vaadin-web-components-no-longer-support-template"></a>The Vaadin Web Components No Longer Support \<template>

The Vaadin Web Components no longer support `<template>` to render content. Use [renderer functions](https://vaadin.com/docs/v23/upgrading/recommended-changes.md#migrate-from-polymertemplate-to-littemplate) instead (see the "Replace Template Elements With Renderers" section). Alternatively, you can use the `@vaadin/polymer-legacy-adapter` package which has been created to maintain backward compatibility.

#### <a id="installation"></a>Installation

Install `@vaadin/polymer-legacy-adapter` as follows:

```terminal
npm i @vaadin/polymer-legacy-adapter --save
```

Import `@vaadin/polymer-legacy-adapter/template-renderer.js` before any other components:

```typescript
import '@vaadin/polymer-legacy-adapter/template-renderer.js';
```

#### <a id="deprecation-warning"></a>Deprecation Warning

By default, `template-renderer.js` shows a deprecation warning when `<template>` is used with a component.

To suppress the warning, add the `suppress-template-warning` attribute to the component:

```html
<vaadin-combo-box suppress-template-warning>
    <template>
        Content
    </template>
</vaadin-combo-box>
```

### <a id="component-typescript-apis"></a>Component TypeScript APIs

#### <a id="input-fields-removed-support-for-positive-tab-index"></a>Input Fields: Removed Support for Positive Tab Index

The following general changes have been made to all input field components:

- [Removed support for using positive `tabindex` values](https://github.com/vaadin/web-components/issues/3275) (for example, `tabindex="1"`) on all input field components. This doesn’t cause errors but has no effect. However, setting `tabindex` to `0` or `-1` is still supported. It’s recommended to ensure that input fields are in the correct order in the DOM, instead of overriding the tab order with `tabindex`.

#### <a id="checkbox"></a>Checkbox

- A new `label` property has been introduced to set plain text labels in client-side code, and this should be used instead of wrapping the text inside the element tags:

  ```html
  <vaadin-checkbox>Foo</vaadin-checkbox>
  ```

  ```html
  <vaadin-checkbox label="Foo">
  ```

- Similarly, rich (HTML) labels should be applied using the new `label` slot:

  ```html
  <vaadin-checkbox>
    Foo <b>Bar</b>
  </vaadin-checkbox>
  ```

  ```html
  <vaadin-checkbox>
    <label slot="label">Foo <b>Bar</b></label>
  </vaadin-checkbox>
  ```

- The `value` property of `vaadin-checkbox-group` is immutable in V23.2 and later.

#### <a id="combo-box-2"></a>Combo Box

- No longer extends `vaadin-text-field`.

- Label, error message and the native input element [are now slotted elements](https://github.com/vaadin/web-components/pull/2496) in light DOM instead of inside the component’s shadow DOM.

- [Dropped support](https://github.com/vaadin/web-components/pull/2622) for `iron-input` and `paper-input` from `vaadin-combo-box-light`.

#### <a id="date-picker-2"></a>Date Picker

- No longer extends `vaadin-text-field`.

- Label, error message and the native input element [are now slotted elements](https://github.com/vaadin/web-components/pull/2496) in light DOM instead of inside the component’s shadow DOM.

- Removed the `i18n.calendar` property, as it was unneeded since the toggle button is no longer announced by screen readers.

#### <a id="grid-2"></a>Grid

- `heightByRows` property renamed `allRowsVisible`.

#### <a id="number-field"></a>Number Field

- No longer extends `vaadin-text-field`.

- Label, error message and the native input element [are now slotted elements](https://github.com/vaadin/web-components/pull/2279) in light DOM instead of inside the component’s shadow DOM.

- Removed `maxlength`, `minlength` and `pattern` properties, which didn’t work anyway.

- From V23.2 onward, the `step` property no longer has a default value.

#### <a id="password-field-2"></a>Password Field

- Extends the updated `vaadin-text-field`. See [Text Field](#styling-text-field) changes for details.

- Added the property `i18n.reveal` to provide an accessible label for the password reveal button.

#### <a id="radio-button"></a>Radio Button

- New `label` property and `label` slot introduced to set plain-text and HTML labels, respectively:

  ```html
  <vaadin-radio-button>Label</vaadin-radio-button>

  <vaadin-radio-button>
    <b>This</b> is a <i>rich</i> label
  </vaadin-radio-button>
  ```

  ```html
  <vaadin-radio-button label="Label"></vaadin-radio-button>

  <vaadin-radio-button>
    <label slot="label">
      <b>This</b> is a <i>rich</i> label
    </label>
  </vaadin-radio-button>
  ```

#### <a id="text-field"></a>Text Field

- The native `<input>` and `<label>` elements [are now slotted children](https://github.com/vaadin/web-components/pull/2274), instead of being inside the component’s shadow DOM.

- The `i18n.clear` property has been removed, as the "clear" button is no longer visible to screen readers.

#### <a id="time-picker-2"></a>Time Picker

- No longer extends `vaadin-text-field`.

- The `i18n.selector` property has been removed, as the toggle button is no longer visible to screen readers.

#### <a id="upload-2"></a>Upload

- `i18n.file.clear()` method renamed to `i18n.file.remove()`.

## <a id="after-the-upgrade"></a>After the Upgrade

Run the following command:

```terminal
mvn clean install
```

## <a id="next-up"></a>Next Up

Check the [Recommended Changes](https://vaadin.com/docs/v23/upgrading/recommended-changes.md) chapter to see the further changes that are recommended to conform with Vaadin 23 best practices and to avoid using deprecated APIs and features.
