Docs

Docs

Upgrading Guide

Changes in Vaadin 22

This guide is an overview of behavior altering or incompatible changes in the Vaadin 22. Check it out if you are using Custom Themes, Lit templates and/or TypeScript based Fusion views in your application.

While the Java API has not been changed, some improvements in the new version affect the DOM structure and styling of components. Most of the changes are caused by accessibility fixes to field components like Checkbox, Radio Group, Text Field and others.

Lumo Adjustments

  • Updated Lumo colors to provide better contrast.

  • Adjusted focus outline to improve contrast.

  • Adjusted input placeholder styles to increase text color contrast.

  • Minor tweaks to light palette shade colors (50–70pct).

  • Minor tweaks to dark palette tint colors (60–70pct).

Common Changes

+ :host([has-error-message]) [part='error-message']::before,
+ :host([has-error-message]) [part='error-message']::after {
- [part='error-message']:not(:empty)::before,
- [part='error-message']:not(:empty)::after {
    height: 0.25rem;
  }

Web Components Changes

Basic Layouts

  • Changed to use CSS gap property instead of margins for spacing between layout items.

  • Setting the display property on the layouts to anything else than flex is not supported.

  • If you’ve used margin CSS property on the layout items, note that those will now be in addition to the layout spacing (previously, any custom margins would override the spacing).

Button

Checkbox

  • Re-implemented the component using slotted <input> and <label> elements.

  • Removed the label shadow part. Apply styles to the slotted <label> instead:

- [part="label"] {
+ ::slotted(label) {
  font-size: 15px;
}

  • Use the newly added label property to set text label.

- <vaadin-checkbox>Yes, I agree</vaadin-checkbox>
+ <vaadin-checkbox label="Yes, I agree"></vaadin-checkbox>

  • Use the newly added named slot to provide label as HTML.

<vaadin-checkbox>
+ <label slot="label">
  I accept <a href="https://example.com">the terms and conditions</a>
+ </label>
</vaadin-checkbox>

Checkbox Group

Combo Box

  • Re-implemented the component using slotted <input> and <label> elements.

  • Replaced <vaadin-text-field> component with <vaadin-input-container>.

  • Replaced <iron-list> component with a custom virtual scroller implementation.

  • Renamed text-field shadow part to input-field to align with the input fields.

  • Moved the <vaadin-combo-box-item> components from Shadow DOM to light DOM.

  • Added "checkmark" part to <vaadin-combo-box-item> for styling selected item.

  • Dropped support for iron-input and paper-input from <vaadin-combo-box-light>.

Date Picker

  • Re-implemented the component using slotted <input> and <label> elements.

  • Replaced <vaadin-date-picker-text-field> component with <vaadin-input-container>.

  • Renamed text-field shadow part to input-field to align with the input fields.

  • Removed i18n.calendar as the toggle button is no longer announced by screen readers.

  • Improved calendar text contrast by using different color and opacity.

Date Time Picker

Grid

Number Field

  • Changed <vaadin-number-field> to no longer extend <vaadin-text-field>.

  • Re-implemented the component using slotted <input> and <label> elements.

  • Removed the value shadow part. Apply styles to the slotted <input> instead:

- [part="value"] {
+ ::slotted(input) {
  font-size: 15px;
}

- [part="value"]::placeholder {
+ ::slotted(input:placeholder-shown) {
  font-style: italic;
}

  • Removed not working maxlength, minlength and pattern properties.

  • Changed to use Lumo icons for "plus" and "minus" controls.

Password Field

  • Extends the updated <vaadin-text-field> and also uses slotted <input> and <label>.

  • Re-implemented the component to make the reveal password button keyboard focusable.

  • Added i18n.reveal to provide an accessible label for the reveal password button.

Radio Button

  • Re-implemented the component using slotted <input> and <label> elements.

  • Removed the label shadow part. Apply styles to the slotted <label> instead:

- [part="label"] {
+ ::slotted(label) {
  font-size: 15px;
}

  • Use the newly added label property to set text label.

- <vaadin-radio-button value="economy">Economy</vaadin-radio-button>
+ <vaadin-radio-button value="economy" label="Economy"></vaadin-radio-button>

  • Use the newly added named slot to provide label as HTML.

<vaadin-radio-button>
+ <label slot="label">
  <vaadin-horizontal-layout>
    <vaadin-icon icon="vaadin:key"></vaadin-icon>
    <span>Use existing account</span>
  </vaadin-horizontal-layout>
+ </label>
</vaadin-radio-button>

Radio Group

Select

[part='input-field'] ::slotted([slot='value'][placeholder]) { {
  font-style: italic;
}

  • Added input-field part to align with the input fields.

Tabs

Text Area

  • Re-implemented the component using slotted <textarea> and <label> elements.

  • Removed the value shadow part. Apply styles to the slotted <textarea> instead:

- [part="value"] {
+ ::slotted(textarea) {
  font-size: 15px;
}

- [part="value"]::placeholder {
+ ::slotted(textarea:placeholder-shown) {
  font-style: italic;
}

Text Field

  • Re-implemented the component using slotted <input> and <label> elements.

  • Removed the value shadow part. Apply styles to the slotted <input> instead:

- [part="value"] {
+ ::slotted(input) {
  font-size: 15px;
}

- [part="value"]::placeholder {
+ ::slotted(input:placeholder-shown) {
  font-style: italic;
}

  • Removed i18n.clear as the clear button is no longer announced by screen readers.

  • Changed to use animation when preventing invalid input.

Time Picker

  • Re-implemented the component using slotted <input> and <label> elements.

  • Replaced <vaadin-time-picker-text-field> component with <vaadin-input-container>.

  • Replaced <vaadin-combo-box-overlay> and <vaadin-combo-box-item> with extensions.

  • Removed i18n.selector as the toggle button is no longer announced by screen readers.

  • Added input-field part to align with the input fields.

Upload

Updated 2022-01-18