> Markdown version of [Upgrade Guide Generator](https://vaadin.com/docs/v23/upgrading/upgrade-tool). Section index: [llms.txt](https://vaadin.com/docs/v23/upgrading/llms.txt)

# Upgrade Guide Generator

<!-- Vale Vaadin.Versions = NO -->

Instructions for upgrading to the latest Vaadin version. To run applications or components developed with Vaadin 7 or 8 inside an application written using the latest version, see [Multiplatform Runtime](https://vaadin.com/docs/v23/tools/mpr/overview.md).

<!-- Vale Vaadin.Versions = YES -->

`upgrade-tool.ts`

```typescript
import '@vaadin/button';
import '@vaadin/select';
import '@vaadin/checkbox';
import '@vaadin/checkbox-group';
import '@vaadin/details';
import '@vaadin/notification';
import { html, LitElement } from 'lit';
import { customElement, state } from 'lit/decorators.js';
import type { Checkbox } from '@vaadin/checkbox';
import type { CheckboxGroupValueChangedEvent } from '@vaadin/checkbox-group';
import { Notification } from '@vaadin/notification';
import type { SelectValueChangedEvent } from '@vaadin/select';
import { selectRenderer } from '@vaadin/select/lit.js';
import { applyTheme } from 'Frontend/generated/theme';

const VAADIN_VERSIONS: Record<string, string> = {
  14: '14.14.9',
  15: '15.0.6',
  16: '16.0.5',
  17: '17.0.11',
  18: '18.0.7',
  19: '19.0.9',
  20: '20.0.8',
  21: '21.0.9',
  22: '22.0.28',
  23: '23.6.19',
};

const SIMPLE_VERSIONS = Object.keys(VAADIN_VERSIONS);

const DEFAULT_FROM = '14';
const DEFAULT_TO = '23';

const HARDCODED_VERSIONS_CLASS = 'vaadin-to-version-full';

// Apply the theme, so that overlay elements styles and custom property overrides work as expected
applyTheme(document);

@customElement('upgrade-tool')
export default class UpgradeTool extends LitElement {
  @state()
  private fromVersion = '';

  @state()
  private toVersion = '';

  @state()
  private frameworkValue: string[] = [];

  @state()
  private extraSettingsValue: string[] = [];

  private isFlow = true;
  private isFusion = false;
  private isSpring = true;
  private isTypeScript = false;
  private isCustomStyling = false;
  private isInstructionsDisplayed = false;
  private isFirstUpdated = false;

  protected override render() {
    return html`
      <div>
        <h2>Select your Vaadin versions:</h2>
        <div style="margin-bottom: 10px">${this.createSelectComponents()}</div>
        <vaadin-details>
          <div slot="summary">Earlier Versions</div>
          <ul style="margin-top: 0">
            <li>
              <a href="https://vaadin.com/docs/v14/flow/upgrading/v10-13">
                Upgrading from Vaadin 10–13 to Vaadin 14
              </a>
            </li>
            <li>
              <a href="https://vaadin.com/docs/v14/flow/upgrading/v8">
                Upgrading from Vaadin 8 to Vaadin 14
              </a>
            </li>
          </ul>
        </vaadin-details>
        <div style="margin-bottom: 10px">
          <vaadin-checkbox-group
            label="Framework"
            id="framework-checkbox-group"
            .value="${this.frameworkValue}"
            @value-changed=${this.frameworkChanged}
            theme="horizontal"
          >
            <vaadin-checkbox value="flow" label="Flow" id="flow-checkbox"></vaadin-checkbox>
            <vaadin-checkbox
              value="fusion"
              label="Fusion/Hilla"
              id="fusion-checkbox"
            ></vaadin-checkbox>
          </vaadin-checkbox-group>
        </div>
        <div>
          <vaadin-checkbox-group
            label="I use"
            id="extra-settings-checkbox-group"
            .value="${this.extraSettingsValue}"
            @value-changed=${this.extraSettingsChanged}
            theme="horizontal"
          >
            <vaadin-checkbox
              value="spring"
              label="Spring Boot"
              id="spring-checkbox"
              ?disabled=${this.isFusion || (!this.isFusion && !this.isFlow)}
            ></vaadin-checkbox>
            <vaadin-checkbox
              value="typescript"
              label="TypeScript-based views"
              id="typescript-checkbox"
              ?disabled=${this.isFusion || (!this.isFusion && !this.isFlow)}
            ></vaadin-checkbox>
            <vaadin-checkbox
              value="styling"
              label="Changes to custom styling of components"
              id="styling-checkbox"
            ></vaadin-checkbox>
          </vaadin-checkbox-group>
        </div>
        <vaadin-button
          theme="primary"
          style="width: fit-content; margin-top: 30px; margin-bottom: 30px"
          @click=${this.showUpdateInstructions}
        >
          Show update instructions!
        </vaadin-button>
      </div>
    `;
  }

  createRenderRoot() {
    return this;
  }

  private showUpdateInstructions() {
    this.hideOldInstructions();
    this.replaceHardCodedVersions();

    if (this.isFlow || this.isFusion) {
      this.showElementsWithClassname('all');
    } else {
      Notification.show('Select a framework');
      return;
    }

    const versionSectionElements: HTMLElement[] = this.getVersionSectionElements(
      this.fromVersion,
      this.toVersion
    );
    versionSectionElements.forEach((e) => this.setElementVisible(e, true));

    if (this.isSpring) {
      this.showElementsWithClassname('spring');
    }

    if (this.isTypeScript) {
      this.showElementsWithClassname('ts');
    }

    if (this.isCustomStyling) {
      this.showElementsWithClassname('styling');
    }

    if (this.isFlow) {
      this.showElementsWithClassname('flow');
    }

    if (this.isFusion) {
      this.showElementsWithClassname('fusion');
    }

    // A one time hack for 14 -> 23 upgrade
    this.perform14To23CleanupIfNecessary();

    this.isInstructionsDisplayed = true;
    this.updateUrlParameters();
  }

  private hideMatchingElements(types: string[]) {
    const selector = types.map((type) => `[class*="${type}"]`).join(', ');

    document.querySelectorAll<HTMLElement>(selector).forEach((elem) => {
      this.setElementVisible(elem, false);
    });
  }

  private perform14To23CleanupIfNecessary() {
    if (!this.is14To23Upgrade()) {
      return;
    }

    this.hideMatchingElements(['all', 'spring']);
  }

  private is14To23Upgrade() {
    return this.fromVersion === '14' && this.toVersion === '23';
  }

  private showElementsWithClassname(classname: string) {
    this.getElementsByClassname(classname).forEach((e) => this.setElementVisible(e, true));
  }

  private getVersionSectionElements(fromVersion: string, toVersion: string) {
    const elementsToShow: HTMLElement[] = [];
    const classname = `v${fromVersion}-${toVersion}`;
    const elements = this.getElementsByClassname(classname);

    if (elements.length > 0) {
      elementsToShow.push(...elements);
    } else {
      const idx = SIMPLE_VERSIONS.indexOf(fromVersion);
      const nextVersion = SIMPLE_VERSIONS[idx + 1];
      elementsToShow.push(...this.getVersionSectionElements(fromVersion, nextVersion));
      elementsToShow.push(...this.getVersionSectionElements(nextVersion, toVersion));
    }

    return elementsToShow;
  }

  private setElementVisible(element: HTMLElement, isVisible: boolean): void {
    if (isVisible) {
      element.style.setProperty('display', 'block');
    } else {
      element.style.setProperty('display', 'none');
    }
  }

  private getElementsByClassname(classname: string) {
    return [...document.querySelectorAll<HTMLElement>(`.${classname}`)];
  }

  private hideOldInstructions() {
    this.hideMatchingElements([
      'all',
      'flow',
      'fusion',
      'spring',
      'ts',
      'styling',
      'v1',
      'v2',
      'v3',
      'v4',
    ]);

    this.isInstructionsDisplayed = false;
  }

  private replaceHardCodedVersions() {
    this.getElementsByClassname(HARDCODED_VERSIONS_CLASS).forEach((e) => {
      e.textContent = VAADIN_VERSIONS[this.toVersion];
    });
  }

  private createSelectComponents() {
    const fromVersionList = SIMPLE_VERSIONS.slice(0, -1);
    const toVersionList = SIMPLE_VERSIONS.slice(1);
    return html`
      <vaadin-select
        label="From"
        id="from-select"
        style="width: fit-content; margin-right: 10px"
        value=${this.fromVersion}
        @value-changed=${this.fromVersionChanged}
        ${selectRenderer(
          () => html`
            <vaadin-list-box>
              ${fromVersionList.map((v) => html`<vaadin-item value="${v}">${v}</vaadin-item>`)}
            </vaadin-list-box>
          `,
          []
        )}
      ></vaadin-select>
      <vaadin-select
        label="To"
        id="to-select"
        value=${this.toVersion}
        @value-changed=${this.toVersionChanged}
        ${selectRenderer(
          () => html`
            <vaadin-list-box>
              ${toVersionList.map(
                (v) =>
                  html`
                    <vaadin-item value="${v}" ?hidden=${v <= this.fromVersion}>${v}</vaadin-item>
                  `
              )}
            </vaadin-list-box>
          `,
          []
        )}
      ></vaadin-select>
    `;
  }

  private fromVersionChanged(e: SelectValueChangedEvent) {
    if (!this.isFirstUpdated) {
      return;
    }

    const val = e.detail.value;
    if (parseInt(val) >= parseInt(this.toVersion)) {
      const idx = SIMPLE_VERSIONS.indexOf(val);
      this.toVersion = SIMPLE_VERSIONS[idx + 1];
    }
    this.fromVersion = val;
    this.updateUrlParameters();
  }

  private toVersionChanged(e: SelectValueChangedEvent) {
    if (!this.isFirstUpdated) {
      return;
    }

    this.toVersion = e.detail.value;
    this.updateUrlParameters();
  }

  private frameworkChanged(e: CheckboxGroupValueChangedEvent) {
    if (!this.isFirstUpdated) {
      return;
    }

    const val = e.detail.value;
    this.frameworkValue = val;

    this.isFlow = val.includes('flow');

    if (this.frameworkValue.includes('fusion')) {
      this.isFusion = true;
      this.isSpring = true;
      this.isTypeScript = true;

      ['spring', 'typescript'].forEach((v) => {
        if (!this.extraSettingsValue.includes(v)) {
          this.extraSettingsValue.push(v);
        }
        const checkbox = document.getElementById(`${v}-checkbox`) as Checkbox;
        checkbox.checked = true;
      });
    } else {
      this.isFusion = false;
    }

    this.updateUrlParameters();
  }

  private extraSettingsChanged(e: CheckboxGroupValueChangedEvent) {
    if (!this.isFirstUpdated) {
      return;
    }

    const val = e.detail.value;
    this.extraSettingsValue = val;

    this.isSpring = val.includes('spring') || this.isFusion;
    this.isTypeScript = val.includes('typescript') || this.isFusion;
    this.isCustomStyling = val.includes('styling');

    this.updateUrlParameters();
  }

  private updateUrlParameters() {
    const urlParams = new URLSearchParams(window.location.search);
    urlParams.set('from', this.fromVersion);
    urlParams.set('to', this.toVersion);
    urlParams.set('isFlow', String(this.isFlow));
    urlParams.set('isFusion', String(this.isFusion));
    urlParams.set('isSpring', String(this.isSpring));
    urlParams.set('isTypeScript', String(this.isTypeScript));
    urlParams.set('isCustomStyling', String(this.isCustomStyling));
    urlParams.set('isInstructionsDisplayed', String(this.isInstructionsDisplayed));

    const pathname = location.pathname.replace(/\/$/, '');
    window.history.replaceState({}, '', `${pathname}/?${urlParams}`);
  }

  private getParamVal(urlParams: URLSearchParams, param: string) {
    const isParam = urlParams.get(param);

    if (isParam) {
      const property = Boolean(JSON.parse(isParam));
      return property;
    }

    return null;
  }

  private initializeProperties() {
    if (this.isFlow) {
      this.frameworkValue.push('flow');
    }
    if (this.isFusion) {
      this.frameworkValue.push('fusion');
    }

    if (this.isSpring) {
      this.extraSettingsValue.push('spring');
    }
    if (this.isTypeScript) {
      this.extraSettingsValue.push('typescript');
    }
    if (this.isCustomStyling) {
      this.extraSettingsValue.push('styling');
    }

    this.frameworkValue = [...this.frameworkValue];
    this.extraSettingsValue = [...this.extraSettingsValue];
  }

  connectedCallback() {
    super.connectedCallback();
    this.removeLinksFromHeaders();
  }

  private removeLinksFromHeaders() {
    // Remove links from headers as clicking them resets the query parameters.
    const anchors = document.getElementsByTagName('a');
    Array.from(anchors).forEach((a) => {
      const parent = a.parentNode;
      if (parent && parent.nodeName === 'H2') {
        a.remove();
      }
    });
  }

  protected override firstUpdated() {
    const urlParams = new URLSearchParams(window.location.search);
    const fromParam = urlParams.get('from');
    const toParam = urlParams.get('to');

    this.fromVersion = fromParam ?? DEFAULT_FROM;
    this.toVersion = toParam ?? DEFAULT_TO;

    const isFlowParam = this.getParamVal(urlParams, 'isFlow');
    const isFusionParam = this.getParamVal(urlParams, 'isFusion');
    const isSpringParam = this.getParamVal(urlParams, 'isSpring');
    const isTypeScriptParam = this.getParamVal(urlParams, 'isTypeScript');
    const isCustomStylingParam = this.getParamVal(urlParams, 'isCustomStyling');
    const isInstructionsDisplayedParam = this.getParamVal(urlParams, 'isInstructionsDisplayed');

    if (isFlowParam != null) {
      this.isFlow = isFlowParam;
    }
    if (isFusionParam != null) {
      this.isFusion = isFusionParam;
    }
    if (isSpringParam != null) {
      this.isSpring = isSpringParam;
    }
    if (isTypeScriptParam != null) {
      this.isTypeScript = isTypeScriptParam;
    }
    if (isCustomStylingParam != null) {
      this.isCustomStyling = isCustomStylingParam;
    }

    this.initializeProperties();

    this.isFirstUpdated = true;
    this.updateUrlParameters();

    if (isInstructionsDisplayedParam) {
      this.isInstructionsDisplayed = true;
      this.showUpdateInstructions();
    }
  }
}
```

## <a id="before-you-start"></a>Before You Start

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

- Edit the `pom.xml` file and change the Vaadin version to `new version`.

* Update Spring Version.

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

`pom.xml`

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

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

## <a id="vaadin-14-to-23-upgrade-guide"></a>Vaadin 14 to 23 Upgrade Guide

The 14-to-23 upgrading instructions are available in the following [separate chapter](https://vaadin.com/docs/v23/upgrading/essential-steps.md).

## <a id="upgrade-steps-14-15"></a>Upgrade Steps | 14 → 15

### <a id="update-main-layoutview-annotations"></a>Update Main Layout/View Annotations

Several annotations typically placed on the `MainLayout` / `MainView` class must be moved to a class that implements the `AppShellConfigurator` interface, for example:

```java
@PWA(name = "My Vaadin App", shortName = "my-app")
public class AppShell implements AppShellConfigurator {

}
```

see [set of annotations to modify the Bootstrap page](https://vaadin.com/docs/v23/advanced/modifying-the-bootstrap-page.md#java-annotations) for more details.

### <a id="replace-obsolete-apis"></a>Replace Obsolete APIs

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

- Property synchronization methods in `Element` are replaced with similar API in `DomListenerRegistration`: `getSynchronizedPropertyEvents`, `getSynchronizedProperties`, `removeSynchronizedPropertyEvent`, `removeSynchronizedProperty`, `addSynchronizedPropertyEvent`, `addSynchronizedProperty`, `synchronizeProperty`.

- JavaScript execution APIs `executeJavaScript` and `callFunction` in `Element` and `Page` are replaced with similarly named methods that give access to the return value `executeJs` and `callJsFunction`:

- Miscellaneous `Element` methods: `Element(String, boolean)`, `addEventListener(String, DomEventListener, String…​)`

- Device and platform detection methods `WebBrowser#isIOS()`, `WebBrowser#isIPad()`, `BrowserDetails#isSafariOrIOS()`, `BrowserDetails#isIOS()`, `BrowserDetails#isIPad()` are replaced with method in `ExtendedClientDetails`: `isIPad()`, `isIOS()`

- Methods `JsModule#loadMode()` and `Page#addJsModule(String, LoadMode)` for setting the load mode of JsModule are removed since it doesn’t function with JavaScript modules.

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

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

- `ServletHelper` is replaced with `HandlerHelper`

- `ExecutionCanceler` is replaced with `PendingJavaScriptResult`

- The `getBodyAttributes` method in `AbstractTheme`, `Lumo` and `Material` is replaced with `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 with ``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 protected instance method `getApplicationUrl` from `VaadinServlet` is removed

#### <a id="bootstrapping-changes"></a>Bootstrapping Changes

For applications upgraded from earlier versions of Vaadin, client-side bootstrapping requires replacing the usages of the V10-14 `BootstrapHandler` APIs with their `IndexHtmlRequestHandler` API counterparts as described in [*IndexHtmlRequestListener interface*](https://vaadin.com/docs/v23/advanced/modifying-the-bootstrap-page.md#IndexHtmlRequestListener-interface) section.

The reason for this API change is that with client-side bootstrapping the initial page HTML generation is separated from loading the Flow client and creating a server-side `UI` instance.

- In Vaadin 10 to 14 these two steps are combined and the `index.html` page includes the code and configuration needed to start the Flow client engine and link the browser page to the server-side `UI` instance.

- In Vaadin 15+ with client-side bootstrapping the `index.html` page includes only the basic HTML markup and links to the TypeScript UI code. If you have Hilla views, the `UI` isn’t guaranteed to be created, thus is optional. It’s only available after the user navigates to a server-side route.

It’s also possible to continue using the bootstrapping mode in V10-14 with the `useDeprecatedV14Bootstrapping` flag. See how the use the flag in [Configuration Properties](https://vaadin.com/docs/v23/configuration/properties.md).

- Vaadin Fusion doesn’t involve any API breaking changes between versions 14 and 15. See the release notes at <https://github.com/vaadin/platform/releases/tag/15.0.0>.

## <a id="upgrade-steps-15-16"></a>Upgrade Steps | 15 → 16

Vaadin 16 doesn’t involve any API breaking changes. See the release notes at <https://github.com/vaadin/platform/releases/tag/16.0.0>.

## <a id="upgrade-steps-16-17"></a>Upgrade Steps | 16 → 17

### <a id="move-annotations-to-appshellconfigurator"></a>Move Annotations to AppShellConfigurator

The only place where configuring the application with certain annotations is supported is in a class that implements `AppShellConfigurator`.

This applies for v15+ bootstrap mode (the default), but not for v14 legacy bootstrapping. Rather than showing nondeterministic behavior and logging an error, the build fails when any of the following annotations occur outside an `AppShellConfigurator` class:

```
Meta.class, PWA.class, Inline.class, Viewport.class, BodySize.class, Push.class
```

### <a id="replace-obsolete-apis-2"></a>Replace Obsolete APIs

#### <a id="a-new-api-for-binding-items-to-components"></a>A New API for Binding Items to Components:

- `HasDataProvider` and `HasItems` are now replaced by the new `HasListDataView`, `HasLazyDataView` and `HasDataView` interfaces in `Grid`, `Select` and `CheckBoxGroup`. It’s also gradually replaced in other components which have an items binding.

- `setDataProvider()` is now deprecated and it’s recommended to use overloaded `setItems()` methods.

- `setItems()` methods now have a return type instead of void.

- the `HasItemsAndComponents` interface has been replaced by `HasItemComponents` to support the Data View API in in-memory binding components.

- `HasHierarchicalDataProvider` no longer has `setItems()` overloads for `Collection`, `Stream` and `Array`.

#### <a id="url-parameters-template-feature"></a>URL Parameters Template Feature

- `BeforeEvent` has a bunch of new methods for forwarding, rerouting and getting the parameters. Some methods are now deprecated or removed.

- The `RouteRegistry` and `SessionRouteRegistry` interfaces are now supplemented with new methods and deprecate getters for route layouts.

- `com.vaadin.flow.server.startup.RouteTarget` has been completely removed. This class was internal and shouldn’t have been used. If you have been using it, you can create an issue describing what you needed it for.

## <a id="upgrade-steps-17-18"></a>Upgrade Steps | 17 → 18

- Using `LitTemplate` is recommended over the deprecated `PolymerTemplate` to do layouts with HTML and UI logic in Java.

It’s recommended to use TypeScript for the template and this has been updated to the examples in the [documentation](https://vaadin.com/docs/v23/create-ui/templates.md).

- Starting from Vaadin 18, the initial attribute values in the template are reflected to the server side state when `@Id` mapping components. This applies to `PolymerTemplate`, too. More information on the template support is available in this [blog post](https://vaadin.com/blog/future-of-html-templates-in-vaadin).

### <a id="flow-breaking-changes"></a>Flow Breaking Changes

- `AppShellRegistry` method `getTitle()` is removed It was broken and couldn’t work. Instead, if needed, use `getUI().getUIInternals().getAppShellTitle()`.

- Having the `@Theme` annotation on Flow views or router layouts is no longer allowed. The annotation should be on `AppShellConfigurator` instead. This is now consistent with the `@PWA` annotation. It’s also cleaner, since you can only have one `@Theme` per application.

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

### <a id="fusion-breaking-changes"></a>Fusion Breaking Changes

- The `value` property of `BinderNode` now has optionally `undefined` type for non-initialized optional fields.

## <a id="upgrade-steps-18-19"></a>Upgrade Steps | 18 → 19

- Vaadin Flow doesn’t involve any API breaking changes between versions 18 and 19. See the release notes at <https://github.com/vaadin/platform/releases/tag/19.0.0>.

### <a id="fusion-breaking-changes-2"></a>Fusion Breaking Changes

#### <a id="generated-id-field-is-now-of-optional-type-in-typescript"></a>Generated @Id Field Is Now of Optional Type in TypeScript

A field with `@Id` annotation in Java is now of optional type in the generated TypeScript code. Given an entity with an `id` field:

`Entity.java`

```java
public class Entity {
    @Id
    private int id;
}
```

Now in the TypeScript files, instead of using `endpoint.getEntity(entity.id)`, you might need to change to `endpoint.getEntity(entity.id!)` (if you know that the `id` is always set when this is called) or add a type guard to explicitly check that `id` isn’t `undefined`.

### <a id="ignore-one-more-service-worker-related-static-file"></a>Ignore One More Service Worker Related Static File

You need to ignore one more static file, `/sw-runtime-resources-precache.js`, if you use `HttpSecurity.authorizeRequests()` to do role-based authorization in your security configuration as follows:

`SecurityConfiguration.java`

```java
@Override
protected void configure(HttpSecurity http) throws Exception {
    ...
    http.authorizeRequests().anyRequest().hasAnyAuthority(Role.getAllRoles());
    ...
}
```

In this situation, you need to add one more file `/sw-runtime-resources-precache.js` to the static resource list that Spring Security bypasses:

`SecurityConfiguration.java`

```java
@Override
public void configure(WebSecurity web) {
    web.ignoring().antMatchers(
            // client-side JS code
            "/VAADIN/**",
            ...
            // web application manifest
            "/manifest.webmanifest",
            "/sw.js",
            "/offline-page.html",
            "/sw-runtime-resources-precache.js",
            ...
    );
}
```

### <a id="ignore-the-service-worker-initiated-requests"></a>Ignore the Service Worker Initiated Requests

Another potential Spring Security related breaking change is about using `HttpSecurity.requestCache()` to redirect the user to the intended page after login.

An example of using `HttpSecurity.requestCache()`:

`SecurityConfiguration.java`

```java
@Override
protected void configure(HttpSecurity http) throws Exception {
    ...
    http

    // Register our CustomRequestCache, that saves unauthorized access attempts, so
    // the user is redirected after login.
    .requestCache().requestCache(new CustomRequestCache())

    // Restrict access to our application.
    .and().authorizeRequests()

    // Allow all flow internal requests.
    .requestMatchers(SecurityUtils::isFrameworkInternalRequest).permitAll()
    ...
}
```

Now you need to ignore the service worker initiated requests, otherwise the access attempts are overridden by the service worker requests and Spring can’t redirect you to the intended page. This can be done by inspecting the `Referer` header of the request.

The `SecurityUtils::isFrameworkInternalRequest()` can be updated as follows to also include the service worker initiated requests:

`SecurityUtils.java`

```java
static boolean isFrameworkInternalRequest(HttpServletRequest request) {
    final String parameterValue = request
        .getParameter(ApplicationConstants.REQUEST_TYPE_PARAMETER);
    // Use Referer in header to check if it's a service worker
    // initiated request
    String referer = request.getHeader("Referer");
    boolean isServiceWorkInitiated = (referer != null
                && referer.endsWith("sw.js"));
    return isServiceWorkInitiated
            || parameterValue != null
            && Stream.of(RequestType.values())
                .anyMatch(r -> r.getIdentifier().equals(parameterValue));
}
```

## <a id="upgrade-steps-19-20"></a>Upgrade Steps | 19 → 20

- Vaadin Flow doesn’t involve any API breaking changes between versions 19 and 20. See the release notes at <https://github.com/vaadin/platform/releases/tag/20.0.0>.

### <a id="fusion-breaking-changes-3"></a>Fusion Breaking Changes

### <a id="endpoints-access-is-denied-by-default"></a>Endpoints Access is Denied by Default

Previously, endpoints (methods in classes with `@Endpoint` annotation) without security annotations (one of `@DenyAll`, `@PermitAll`, `@RolesAllowed`, `@AnonymousAllowed`) were accessible by all authenticated users. To avoid inadvertent exposure of methods as endpoints, `@DenyAll` is now the default. This means that you need to add explicit security annotations to the endpoints that you want to make accessible (either at the class level or the method level).

### <a id="default-spring-security-configuration"></a>Default Spring Security Configuration

A default class for Spring Security configuration is available as `VaadinWebSecurityConfigurerAdapter`. Extend this class instead of the default `WebSecurityConfigurerAdapter` to automatically get a configuration that allows Vaadin specific requests to pass through security while requiring authorization for all other requests:

`SecurityConfiguration.java`

```java
@EnableWebSecurity
@Configuration
public class SecurityConfiguration extends VaadinWebSecurityConfigurerAdapter {

    protected void configure(HttpSecurity http) throws Exception {
        super.configure(http);
        // app's own HttpSecurity configuration as needed ...
    }

    @Override
    protected void configure(WebSecurity web) throws Exception {
        super.configure(web);
        // app's own WebSecurity configuration as needed...
    }
}
```

`VaadinWebSecurityConfigurerAdapter` configures authentication for all routes by default. Modify this behavior with your own followup configuration as needed. It also bypasses framework internal and static resources (`/VAADIN/**`, `sw.js` …​). Previously, these had to be explicitly matched and ignored in the app.

`VaadinWebSecurityConfigurerAdapter` also configures Spring Cross-Site Request Forgery (CSRF) token for login and Fusion endpoint requests, so you no longer need to ignore Spring CSRF protection for them like before with `http.csrf().ignoringAntMatchers("/login", "/connect/**");`

The client-side `login()` method now needs the Spring CSRF token returned from a login success handler `VaadinSavedRequestAwareAuthenticationSuccessHandler`. You can update your login view configuration with the `setLoginView()` helper, which sets up the login success handler automatically.

`SecurityConfig.java`

```java
package com.vaadin.demo.fusion.security.authentication;

import com.vaadin.flow.spring.security.VaadinWebSecurityConfigurerAdapter;

import org.springframework.security.config.annotation.authentication.builders.AuthenticationManagerBuilder;
import org.springframework.security.config.annotation.web.builders.HttpSecurity;
import org.springframework.security.config.annotation.web.builders.WebSecurity;

/**
 * An example code for demoing the Spring Security configuration, shouldn't affect
 * the doc application itself.
 */
public class SecurityConfigDemo extends VaadinWebSecurityConfigurerAdapter {

  // tag::login[]
  @Override
  protected void configure(HttpSecurity http) throws Exception {
    super.configure(http);
    setLoginView(http, "/login");
  }
  // end::login[]

  @Override
  protected void configure(AuthenticationManagerBuilder auth) throws Exception {
    // Configure users and roles in memory
    auth.inMemoryAuthentication().withUser("user").password("{noop}password").roles("USER");
  }

  @Override
  public void configure(WebSecurity web) throws Exception {
      super.configure(web);
      web.ignoring().antMatchers("/images/**");
  }
}
```

## <a id="upgrade-steps-20-21"></a>Upgrade Steps | 20 → 21

### <a id="lit-templates-use-lit-2"></a>Lit Templates Use Lit 2

Previously, Lit templates were based on LitElement 2.x and lit-html 1.x. New Lit 2.0 (which includes LitElement 3.x and lit-html 2.x) is used for Lit templates in the latest Vaadin version. Some changes are required to be able to use your existing template with Lit 2.0. See the [Lit Upgrade Guide](https://lit.dev/docs/releases/upgrade/#update-packages-and-import-paths) where you can find all necessary changes. Most of the necessary changes are with imports.

Use the `lit` package. For example, change imports of `html` and `LitElement` from:

```typescript
import { html, LitElement } from 'lit-element';
```

to:

```typescript
import { html, LitElement } from 'lit';
```

Update decorator imports. Decorators have been moved to a separate module. For example, change `customElement` and `property` decorator imports from:

```typescript
import { customElement, property } from 'lit-element';
```

to:

```typescript
import { customElement, property } from 'lit/decorators.js';
```

Update directive imports from:

```typescript
import { repeat } from 'lit-html/directives/repeat.js';
```

to:

```typescript
import { repeat } from 'lit/directives/repeat.js';
```

Some Lit APIs have been renamed. The most noticeable change is that the `@internalProperty` decorator has been renamed to `@state`.

### <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 is 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="positive-tab-index-no-longer-supported-on-input-fields"></a>Positive Tab Index No Longer Supported on Input Fields

Setting the `tabindex` attribute to a value > 0 (for example, by calling `setTabIndex(10)`) is no longer supported on input field components. However, `tabindex` values of 0 and -1 are still supported.

### <a id="fusion-breaking-changes-4"></a>Fusion Breaking Changes

#### <a id="fusion-package-renaming"></a>Fusion Package Renaming

To give Fusion a better identity, the following Fusion packages were renamed:

- `com.vaadin.flow.server.connect` to `com.vaadin.fusion`

- `com.vaadin.flow.server.frontend.fusion` to `com.vaadin.fusion.frontend`

- `com.vaadin.flow.server.startup.fusion` to `com.vaadin.fusion.startup`

#### <a id="typescript-code-generation-nullability-change"></a>TypeScript Code Generation Nullability Change

Previously, all the Java types are generated as required in TypeScript. Now it changes so that for any type that’s nullable in Java, it’s optional in TypeScript, that is, the value could be `undefined`. See [the GitHub issue](https://github.com/vaadin/flow/issues/8849).

To upgrade, you can either: Update the client-side code to handle undefinable value.

```typescript
// The address property is never undefined in Vaadin 20
person.address.street
// Use the question mark to deal with undefinable properties in Vaadin 21
person.address?.street


// The list returned from the endpoint is never undefined in Vaadin 20
const items = await endpoint.list();
// Use the double question mark to give a default value in Vaadin 21
const item = (await endpoint.list()) ?? [];
```

Or use `@Nonnull` annotation on the server-side to keep the same code generation behavior as before.

```java
public class Person {
    @Nonnull
    private Address address;
}
```

> **Tip: @Nonnull annotation**
>
> You can use any `@Nonnull` annotations available or even your own one. Vaadin uses case-insensitive string comparison for checking the annotation.

See [Type Nullability](https://vaadin.com/docs/v22/fusion/advanced/endpoints-generator/#type-nullability) for more details.

## <a id="upgrade-steps-21-22"></a>Upgrade Steps | 21 → 22

### <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 was 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
  <!-- Before -->
  <vaadin-checkbox>Foo</vaadin-checkbox>

  <!-- After -->
  <vaadin-checkbox label="Foo">
  ```

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

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

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

#### <a id="combo-box"></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"></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"></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.

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

- Extends the updated `vaadin-text-field`. See [Text Field](#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
  <!-- Before -->

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

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


  <!-- After -->

  <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"></a>Time Picker

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

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

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

- `i18n.file.clear` method renamed `i18n.file.remove`.

#### <a id="input-fields-removed-support-for-positive-tab-index-2"></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, `setTabIndex(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="fusion-breaking-changes-5"></a>Fusion Breaking Changes

#### <a id="frontend-npm-package"></a>Frontend npm Package

Fusion frontend code was moved from `@vaadin/flow-frontend` to `@vaadin/fusion-frontend`. Fusion module imports need to be updated correspondingly.

For example, importing Fusion `EndpointError` needs to be changed as follows, from:

```typescript
import { EndpointError } from '@vaadin/flow-frontend';
```

to:

```typescript
import { EndpointError } from '@vaadin/fusion-frontend';
```

#### <a id="typescript-4-4-default-catch-variable-type"></a>TypeScript 4.4 Default Catch Variable Type

Vaadin has changed the TypeScript dependency version to 4.4. Starting from this version, the default catch variable type changes in TypeScript from `any` to `unknown`. As a result, there need to be changes to the error handling code that didn’t involve `instanceof` guards.

For example:

```typescript
try {
  await DataEndpoint.getViewData();
} catch (error) {
  console.log(error.message); // Error TS2571: Object is of type 'unknown'.

  if (error instanceof Error) {
    console.log(error.message); // Works.
  }
}

try {
  await DataEndpoint.getViewData();
} catch (error: any) {
  console.log(error.message); // Works, but using `any` isn't recommended.
}
```

See also: [the TypeScript change announcement](https://devblogs.microsoft.com/typescript/announcing-typescript-4-4/#use-unknown-catch-variables:).

#### <a id="positive-tab-index-no-longer-supported-on-input-fields-2"></a>Positive Tab Index No Longer Supported on Input Fields

Setting the `tabindex` attribute to a value > 0 is no longer supported on input field components. However, `tabindex` values of 0 and -1 are still supported.

## <a id="changes-affecting-custom-styling-of-components"></a>Changes Affecting Custom Styling of 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="labels"></a>Labels

Labels have been changed to slotted child elements. While 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
/* Before */
[part="label"]:not(:empty) {...}

/* After */
: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 using it need to be rewritten to use the `has-label` attribute instead:

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

/* After */
:host([has-label]) {...}
```

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

Error messages have been changed to slotted child elements. While 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 with attribute selectors for the appropriate states:

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

/* After */
[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
/* Before */
[part="label"]::after {...}

/* After */
[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 was renamed to `vaadin-field-default-width`:

```css
html {
  /* Before */
  --vaadin-text-field-default-width: 20em;

  /* After */
  --vaadin-field-default-width: 20em;
}
```

#### <a id="text-field-derivatives-refactored"></a>Text Field Derivatives Refactored

The following components used to be based on the Text Field component, and were mostly styled through it:

- Combo Box

- Date Picker

- Number Field and Integer Field

- Select

- Time Picker

These have now been refactored to no longer be based on Text Field, which means that they need to be styled separately from it. See the separate upgrade guides for each of these below.

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

#### <a id="styles-inherited-by-select"></a>Styles Inherited by Select

The [Select](#select) component has been refactored to use an internal button which 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 only apply to actual Buttons by specifying the element name in their selectors:

`vaadin-button.css`

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

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

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

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

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

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

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

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

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
/* Before */
[part="label"] {...}

/* After */
::slotted(label) {...}
```

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

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

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

- 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:

- 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
/* Before */
[content].some-classname {...}

/* After */
::slotted(.some-classname) {...}
```

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

```css
/* Before */
:host::before {...}

/* After */
[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’s 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-2"></a>Date 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 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:

- 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:

- 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
/* Before */
[part="date"] {...}
[part="time"] {...}

/* After */
::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-2"></a>Grid

The color and opacity of inactive sort indicators were 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. While 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
/* Before */
.some-layout-child {
  margin-left: 50px;
}

/* After */
.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
/* Before */
::slotted(iron-icon) {...}

/* After */
::slotted(vaadin-icon) {...}
```

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

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

- See changes to [Text Field](#styling-text-field), as those 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:

- 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-2"></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).

#### <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:

- 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).

```css
/* Before (in styles.css) */
vaadin-select-overlay vaadin-item {...}

/* After (in styles.css) */
vaadin-select-item {...}
```

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

```css
/* Before */
[content].some-classname {...}

/* After */
::slotted(.some-classname) {...}
```

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

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

```css
/* Before */
:host::before {...}

/* After */
[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, and is 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
/* Before (in vaadin-item) */
[part="value"] vaadin-item {...}

/* After (in styles.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
/* Before */
[part="value"]:placeholder-shown {...}

/* After */
::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
/* Before */
[part="value"] {...}

/* After */
::slotted(textarea) {...}
```

This also affects selectors for the placeholder text:

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

/* After */
::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-text-input-components-no-longer-based-on-text-field"></a>Other Text Input Components No Longer Based on Text Field

The following components that used to be based on Text Field are no longer so, and need to be styled separately instead of inheriting styles from Text Field:

- Combo Box

- Date Picker

- Number Field

- Select

- Time Picker

However, the same structural changes were 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
/* Before */
[part="value"] {...}

/* After */
::slotted(input) {...}
```

This also affects selectors for the placeholder text:

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

/* After */
::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-2"></a>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 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:

- 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-2"></a>Upload

The `clear-button` part was renamed `remove-button`:

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

/* After */
[part="remove-button"] {...}
```

## <a id="upgrade-steps-22-23"></a>Upgrade Steps | 22 → 23

<!-- Vale Vaadin.Versions = NO -->

### <a id="npm-as-the-default-frontend-package-manager"></a>npm as the Default Frontend Package Manager

Starting from Vaadin 23, `npm` is used as the default frontend package manager, since the performance of `npm` has been improved and it’s possible to lock dependency versions with the `npm` [overrides feature](https://docs.npmjs.com/cli/v8/configuring-npm/package-json#overrides). `pnpm` is still supported. To continue using `pnpm`, set the [pnpm.enable flag](https://vaadin.com/docs/v23/configuration/npm-pnpm.md) to true.

<!-- Vale Vaadin.Versions = YES -->

### <a id="flow-breaking-changes-2"></a>Flow Breaking Changes

- Java version requirement changes from Java 8 to Java 11

  For Maven update the 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>
  ```

- For Java 9+ `maven-failsafe-plugin` requires jaxb-impl to be added

  The dependency can be added directly in the plugin definition as:

  ```xml
  <plugin>
      <artifactId>maven-failsafe-plugin</artifactId>
      <dependencies>
          <dependency>
              <groupId>com.sun.xml.bind</groupId>
              <artifactId>jaxb-impl</artifactId>
              <version>${jaxb.version}</version>
          </dependency>
      </dependencies>
  </plugin>
  ```

- Frontend package manager changes from pnpm to npm

  The default package manager is now npm, but if using a version older than 8.3 it’s recommended to use pnpm instead.

  To keep using pnpm the configuration pnpm.enable should be set.

  Maven

  ```xml
  <plugin>
      <groupId>com.vaadin</groupId>
      <artifactId>flow-maven-plugin</artifactId>
      <configuration>
          <pnpmEnable>true</pnpmEnable>
      </configuration>
  </plugin>
  ```

  Gradle

  ```groovy
  vaadin {
    pnpmEnable = true
  }
  ```

  Or using the system property `vaadin.pnpm.enable=true`

  > **Note:** Running `npm` without a `package-lock.json` is slow for the initial installation. A project that comes from `pnpm` doesn’t have an `npm` `package-lock.json`, as it uses `pnpm-lock.yaml`.

- Charts CSS styling mode no longer requires importing and including the default charts theme, so these should be removed.

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

  /* After */
  @CssImport(value = "my-chart-styles.css", themeFor = "vaadin-chart")
  ```

### <a id="changes"></a>Changes

- Recommended minimum version of npm is v8.3

  This is to have the support for overrides to lock transitive dependencies versions.

- When the global node isn’t compatible, the version in `~/.vaadin` is used.

  If a version doesn’t exist or is too old it is automatically downloaded and installed.

### <a id="hilla-as-a-standalone-platform"></a>Hilla as a Standalone Platform

Fusion used to be part of the Vaadin platform, now it’s separated from Vaadin and packaged as a standalone platform called Hilla. Hilla and Vaadin work seamlessly together, as long as the versions match. They share the same minor and patch versions; the difference is that Vaadin has 23 as the major version, while Hilla has 1.

### <a id="use-hilla-dependency-instead-of-vaadin"></a>Use Hilla Dependency Instead of Vaadin

For a pure Fusion application, you can update the Vaadin dependency and related artifacts to Hilla. The benefit is that some unnecessary dependencies are excluded, for example, the server-side Flow components. Here is an example of `pom.xml` file updates:

```xml
<!-- use hilla version instead of vaadin -->
<hilla.version>1.0.0</hilla.version>

<!-- use hilla bom instead of vaadin -->
<dependency>
    <groupId>dev.hilla</groupId>
    <artifactId>hilla-bom</artifactId>
    <version>${hilla.version}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

<!-- use hilla dependency instead of vaadin -->
<dependency>
    <groupId>dev.hilla</groupId>
    <artifactId>hilla</artifactId>
</dependency>

<!-- use hilla-spring-boot-starter instead of vaadin-spring-boot-starter -->
<dependency>
    <groupId>dev.hilla</groupId>
    <artifactId>hilla-spring-boot-starter</artifactId>
</dependency>

<!-- use hilla-maven-plugin instead of vaadin-maven-plugin -->
<groupId>dev.hilla</groupId>
<artifactId>hilla-maven-plugin</artifactId>
<version>${hilla.version}</version>
```

There’s no `hilla-core` dependency; both `vaadin` and `vaadin-core` should be replaced with `hilla`.

### <a id="flow-hilla-hybrid-projects"></a>Flow-Hilla Hybrid Projects

If a Flow application needs the Hilla features, such as Endpoint, it can be updated to also include the `hilla` dependency in the `pom.xml` file. Here is an example of how to do that:

```xml
<vaadin.version>23.0.0</vaadin.version>
<!-- add the hilla version -->
<hilla.version>1.0.0</hilla.version>

<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin-bom</artifactId>
    <version>${vaadin.version}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

<!-- add the hilla bom -->
<dependency>
    <groupId>dev.hilla</groupId>
    <artifactId>hilla-bom</artifactId>
    <version>${hilla.version}</version>
    <type>pom</type>
    <scope>import</scope>
</dependency>

<dependency>
    <groupId>com.vaadin</groupId>
    <artifactId>vaadin</artifactId>
</dependency>

<!-- add the hilla dependency -->
<dependency>
    <groupId>dev.hilla</groupId>
    <artifactId>hilla</artifactId>
</dependency>
```

#### <a id="java-package-renaming"></a>Java Package Renaming

The `com.vaadin.fusion` package was renamed to `dev.hilla`, so the Java imports need to be updated accordingly.

For example, importing `Endpoint` needs to be changed as follows, from:

```java
import com.vaadin.fusion.Endpoint;
```

to:

```java
import dev.hilla.Endpoint;
```

#### <a id="front-end-npm-package-renaming"></a>Front-End npm Package Renaming

The front-end code was moved from `@vaadin/flow-frontend` to `@vaadin/fusion-frontend`, and from `@vaadin/form` to `@hilla/form`. The module imports need to be updated correspondingly.

For example, importing `EndpointError`, `Binder` and `field` need to be changed as follows, from:

```typescript
import { EndpointError } from '@vaadin/fusion-frontend';
import { Binder, field } from '@vaadin/form';
```

to:

```typescript
import { EndpointError } from '@hilla/frontend';
import { Binder, field } from '@hilla/form';
```

#### <a id="add-hilla-package-to-whitelisted-packages-list"></a>Add Hilla Package to whitelisted-packages List

Make sure that `dev.hilla` is added to the `vaadin.whitelisted-packages` property inside `application.properties` file. For example, the property should be changed to look something as follows:

`src/main/java/resources/application.properties`

```properties
vaadin.whitelisted-packages = com.vaadin,org.vaadin,com.example.application,dev.hilla
```

## <a id="after-you-finish"></a>After You Finish

- Run the following command:

```terminal
mvn clean install
```
