@vaadin/combo-box 25.0.0-alpha8 → 25.0.0-beta1

package/src/vaadin-combo-box-mixin.js

@@ -3,10 +3,8 @@
  * Copyright (c) 2015 - 2025 Vaadin Ltd.
  * This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
  */
-import { get } from '@vaadin/component-base/src/path-utils.js';
 import { ValidateMixin } from '@vaadin/field-base/src/validate-mixin.js';
-import { ComboBoxBaseMixin } from './vaadin-combo-box-base-mixin.js';
-import { ComboBoxPlaceholder } from './vaadin-combo-box-placeholder.js';
+import { ComboBoxItemsMixin } from './vaadin-combo-box-items-mixin.js';
 
 /**
  * Checks if the value is supported as an item value in this control.
@@ -18,32 +16,14 @@ function isValidValue(value) {
   return value !== undefined && value !== null;
 }
 
-/**
- * Returns the index of the first item that satisfies the provided testing function
- * ignoring placeholder items.
- *
- * @param {Array<ComboBoxItem | string>} items
- * @param {Function} callback
- * @return {number}
- */
-function findItemIndex(items, callback) {
-  return items.findIndex((item) => {
-    if (item instanceof ComboBoxPlaceholder) {
-      return false;
-    }
-
-    return callback(item);
-  });
-}
-
 /**
  * @polymerMixin
- * @mixes ComboBoxBaseMixin
+ * @mixes ComboBoxItemsMixin
  * @mixes ValidateMixin
  * @param {function(new:HTMLElement)} superClass
  */
 export const ComboBoxMixin = (superClass) =>
-  class ComboBoxMixinClass extends ValidateMixin(ComboBoxBaseMixin(superClass)) {
+  class ComboBoxMixinClass extends ValidateMixin(ComboBoxItemsMixin(superClass)) {
     static get properties() {
       return {
         /**
@@ -63,17 +43,6 @@ export const ComboBoxMixin = (superClass) =>
           sync: true,
         },
 
-        /**
-         * A full set of items to filter the visible options from.
-         * The items can be of either `String` or `Object` type.
-         * @type {!Array<!ComboBoxItem | string> | undefined}
-         */
-        items: {
-          type: Array,
-          sync: true,
-          observer: '_itemsChanged',
-        },
-
         /**
          * If `true`, the user can input a value that is not present in the items list.
          * `value` property will be set to the input value in this case.
@@ -87,18 +56,6 @@ export const ComboBoxMixin = (superClass) =>
           value: false,
         },
 
-        /**
-         * A subset of items, filtered based on the user input. Filtered items
-         * can be assigned directly to omit the internal filtering functionality.
-         * The items can be of either `String` or `Object` type.
-         * @type {!Array<!ComboBoxItem | string> | undefined}
-         */
-        filteredItems: {
-          type: Array,
-          observer: '_filteredItemsChanged',
-          sync: true,
-        },
-
         /**
          * When set to `true`, "loading" attribute is added to host and the overlay element.
          * @type {boolean}
@@ -110,17 +67,6 @@ export const ComboBoxMixin = (superClass) =>
           sync: true,
         },
 
-        /**
-         * Filtering string the user has typed into the input field.
-         * @type {string}
-         */
-        filter: {
-          type: String,
-          value: '',
-          notify: true,
-          sync: true,
-        },
-
         /**
          * The selected item from the `items` array.
          * @type {ComboBoxItem | string | undefined}
@@ -141,39 +87,6 @@ export const ComboBoxMixin = (superClass) =>
           type: Object,
         },
 
-        /**
-         * Path for label of the item. If `items` is an array of objects, the
-         * `itemLabelPath` is used to fetch the displayed string label for each
-         * item.
-         *
-         * The item label is also used for matching items when processing user
-         * input, i.e., for filtering and selecting items.
-         * @attr {string} item-label-path
-         * @type {string}
-         */
-        itemLabelPath: {
-          type: String,
-          value: 'label',
-          observer: '_itemLabelPathChanged',
-          sync: true,
-        },
-
-        /**
-         * Path for the value of the item. If `items` is an array of objects, the
-         * `itemValuePath:` is used to fetch the string value for the selected
-         * item.
-         *
-         * The item value is used in the `value` property of the combo box,
-         * to provide the form value.
-         * @attr {string} item-value-path
-         * @type {string}
-         */
-        itemValuePath: {
-          type: String,
-          value: 'value',
-          sync: true,
-        },
-
         /**
          * Path for the id of the item. If `items` is an array of objects,
          * the `itemIdPath` is used to compare and identify the same item
@@ -245,10 +158,6 @@ export const ComboBoxMixin = (superClass) =>
           this._scroller[prop] = this[prop];
         }
       });
-
-      if (props.has('filter')) {
-        this._filterChanged(this.filter);
-      }
     }
 
     /** @private */
@@ -301,28 +210,6 @@ export const ComboBoxMixin = (superClass) =>
       }
     }
 
-    /**
-     * Override method from `ComboBoxBaseMixin` to handle item label path.
-     * @protected
-     * @override
-     */
-    _getItemLabel(item) {
-      let label = item && this.itemLabelPath ? get(this.itemLabelPath, item) : undefined;
-      if (label === undefined || label === null) {
-        label = item ? item.toString() : '';
-      }
-      return label;
-    }
-
-    /** @private */
-    _getItemValue(item) {
-      let value = item && this.itemValuePath ? get(this.itemValuePath, item) : undefined;
-      if (value === undefined) {
-        value = item ? item.toString() : '';
-      }
-      return value;
-    }
-
     /**
      * Override method from `ComboBoxBaseMixin` to handle loading.
      * @protected
@@ -488,37 +375,6 @@ export const ComboBoxMixin = (superClass) =>
       this._clearFilter();
     }
 
-    /**
-     * Override an event listener from `ComboBoxBaseMixin` to handle
-     * batched setting of both `opened` and `filter` properties.
-     * @param {!Event} event
-     * @protected
-     * @override
-     */
-    _onInput(event) {
-      const filter = this._inputElementValue;
-
-      // When opening dropdown on user input, both `opened` and `filter` properties are set.
-      // Perform a batched property update instead of relying on sync property observers.
-      // This is necessary to avoid an extra data-provider request for loading first page.
-      const props = {};
-
-      if (this.filter === filter) {
-        // Filter and input value might get out of sync, while keyboard navigating for example.
-        // Afterwards, input value might be changed to the same value as used in filtering.
-        // In situation like these, we need to make sure all the filter changes handlers are run.
-        this._filterChanged(this.filter);
-      } else {
-        props.filter = filter;
-      }
-
-      if (!this.opened && !this._isClearButton(event) && !this.autoOpenDisabled) {
-        props.opened = true;
-      }
-
-      this.setProperties(props);
-    }
-
     /**
      * Override an event listener from `InputMixin`.
      * @param {!Event} event
@@ -531,30 +387,6 @@ export const ComboBoxMixin = (superClass) =>
       event.stopPropagation();
     }
 
-    /** @private */
-    _itemLabelPathChanged(itemLabelPath) {
-      if (typeof itemLabelPath !== 'string') {
-        console.error('You should set itemLabelPath to a valid string');
-      }
-    }
-
-    /** @private */
-    _filterChanged(filter) {
-      // Scroll to the top of the list whenever the filter changes.
-      this._scrollIntoView(0);
-
-      this._focusedIndex = -1;
-
-      if (this.items) {
-        this.filteredItems = this._filterItems(this.items, filter);
-      } else {
-        // With certain use cases (e. g., external filtering), `items` are
-        // undefined. Filtering is unnecessary per se, but the filteredItems
-        // observer should still be invoked to update focused item.
-        this._filteredItemsChanged(this.filteredItems);
-      }
-    }
-
     /**
      * Override method from `ComboBoxBaseMixin` to handle reverting value.
      * @protected
@@ -651,40 +483,6 @@ export const ComboBoxMixin = (superClass) =>
       }
     }
 
-    /** @private */
-    _itemsChanged(items, oldItems) {
-      this._ensureItemsOrDataProvider(() => {
-        this.items = oldItems;
-      });
-
-      if (items) {
-        this.filteredItems = items.slice(0);
-      } else if (oldItems) {
-        // Only clear filteredItems if the component had items previously but got cleared
-        this.filteredItems = null;
-      }
-    }
-
-    /** @private */
-    _filteredItemsChanged(filteredItems) {
-      this._setDropdownItems(filteredItems);
-    }
-
-    /** @private */
-    _filterItems(arr, filter) {
-      if (!arr) {
-        return arr;
-      }
-
-      const filteredItems = arr.filter((item) => {
-        filter = filter ? filter.toString().toLowerCase() : '';
-        // Check if item contains input value.
-        return this._getItemLabel(item).toString().toLowerCase().indexOf(filter) > -1;
-      });
-
-      return filteredItems;
-    }
-
     /** @private */
     _selectItemForValue(value) {
       const valueIndex = this.__getItemIndexByValue(this.filteredItems, value);
@@ -708,6 +506,7 @@ export const ComboBoxMixin = (superClass) =>
      * Override this method to show custom items.
      *
      * @protected
+     * @override
      */
     _setDropdownItems(newItems) {
       const oldItems = this._dropdownItems;
@@ -740,37 +539,6 @@ export const ComboBoxMixin = (superClass) =>
       }
     }
 
-    /**
-     * Returns the first item that matches the provided value.
-     *
-     * @private
-     */
-    __getItemIndexByValue(items, value) {
-      if (!items || !isValidValue(value)) {
-        return -1;
-      }
-
-      return findItemIndex(items, (item) => {
-        return this._getItemValue(item) === value;
-      });
-    }
-
-    /**
-     * Returns the first item that matches the provided label.
-     * Labels are matched against each other case insensitively.
-     *
-     * @private
-     */
-    __getItemIndexByLabel(items, label) {
-      if (!items || !label) {
-        return -1;
-      }
-
-      return findItemIndex(items, (item) => {
-        return this._getItemLabel(item).toString().toLowerCase() === label.toString().toLowerCase();
-      });
-    }
-
     /**
      * Override method from `ComboBoxBaseMixin`.
      * @protected

package/src/vaadin-combo-box-overlay-mixin.js

@@ -22,21 +22,6 @@ export const ComboBoxOverlayMixin = (superClass) =>
       this.requiredVerticalSpace = 200;
     }
 
-    /** @protected */
-    connectedCallback() {
-      super.connectedCallback();
-
-      const hostDir = this._getHostDir();
-      if (hostDir) {
-        this.setAttribute('dir', hostDir);
-      }
-    }
-
-    /** @protected */
-    _getHostDir() {
-      return this.owner && this.owner.getAttribute('dir');
-    }
-
     /**
      * Override method inherited from `Overlay`
      * to not close on position target click.
@@ -66,16 +51,7 @@ export const ComboBoxOverlayMixin = (superClass) =>
 
     /** @protected */
     _updateOverlayWidth() {
-      const propPrefix = this.localName;
-      this.style.setProperty(`--_${propPrefix}-default-width`, `${this.positionTarget.offsetWidth}px`);
-
-      const customWidth = getComputedStyle(this.owner).getPropertyValue(`--${propPrefix}-width`);
-
-      if (customWidth === '') {
-        this.style.removeProperty(`--${propPrefix}-width`);
-      } else {
-        this.style.setProperty(`--${propPrefix}-width`, customWidth);
-      }
+      this.style.setProperty(`--_${this.localName}-default-width`, `${this.positionTarget.offsetWidth}px`);
     }
 
     /** @private */

package/src/vaadin-combo-box-overlay.js

@@ -7,11 +7,11 @@ import { html, LitElement } from 'lit';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { DirMixin } from '@vaadin/component-base/src/dir-mixin.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
-import { overlayStyles } from '@vaadin/overlay/src/styles/vaadin-overlay-core-styles.js';
+import { overlayStyles } from '@vaadin/overlay/src/styles/vaadin-overlay-base-styles.js';
 import { OverlayMixin } from '@vaadin/overlay/src/vaadin-overlay-mixin.js';
 import { LumoInjectionMixin } from '@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
-import { comboBoxOverlayStyles } from './styles/vaadin-combo-box-overlay-core-styles.js';
+import { comboBoxOverlayStyles } from './styles/vaadin-combo-box-overlay-base-styles.js';
 import { ComboBoxOverlayMixin } from './vaadin-combo-box-overlay-mixin.js';
 
 /**

package/src/vaadin-combo-box-scroller-mixin.d.ts

@@ -45,8 +45,7 @@ export declare class ComboBoxScrollerMixinClass<TItem, TOwner> {
   owner: TOwner;
 
   /**
-   * Set true to prevent the overlay from opening automatically.
-   * @attr {boolean} auto-open-disabled
+   * Function used to render the content of every combo-box item.
    */
   renderer: ComboBoxItemRenderer<TItem, TOwner> | null | undefined;
 

package/src/vaadin-combo-box-scroller-mixin.js

@@ -234,6 +234,11 @@ export const ComboBoxScrollerMixin = (superClass) =>
         scrollTarget: this,
         scrollContainer: this.$.selector,
         reorderElements: true,
+        // Combo-box items have a CSS-defined minimum height, so the virtualizer's
+        // height placeholder logic can be disabled. This helps save reflows which
+        // might otherwise be triggered by this logic because it reads the row height
+        // right after updating the rows' content.
+        __disableHeightPlaceholder: true,
       });
     }
 

package/src/vaadin-combo-box-scroller.js

@@ -6,7 +6,7 @@
 import { html, LitElement } from 'lit';
 import { defineCustomElement } from '@vaadin/component-base/src/define.js';
 import { PolylitMixin } from '@vaadin/component-base/src/polylit-mixin.js';
-import { comboBoxScrollerStyles } from './styles/vaadin-combo-box-scroller-core-styles.js';
+import { comboBoxScrollerStyles } from './styles/vaadin-combo-box-scroller-base-styles.js';
 import { ComboBoxScrollerMixin } from './vaadin-combo-box-scroller-mixin.js';
 
 /**

package/src/vaadin-combo-box.d.ts

@@ -9,7 +9,6 @@ import type { FocusMixinClass } from '@vaadin/a11y-base/src/focus-mixin.js';
 import type { KeyboardMixinClass } from '@vaadin/a11y-base/src/keyboard-mixin.js';
 import type { DelegateStateMixinClass } from '@vaadin/component-base/src/delegate-state-mixin.js';
 import type { ElementMixinClass } from '@vaadin/component-base/src/element-mixin.js';
-import type { OverlayClassMixinClass } from '@vaadin/component-base/src/overlay-class-mixin.js';
 import type { ClearButtonMixinClass } from '@vaadin/field-base/src/clear-button-mixin.js';
 import type { FieldMixinClass } from '@vaadin/field-base/src/field-mixin.js';
 import type { InputConstraintsMixinClass } from '@vaadin/field-base/src/input-constraints-mixin.js';
@@ -22,6 +21,7 @@ import type { ThemableMixinClass } from '@vaadin/vaadin-themable-mixin/vaadin-th
 import type { ThemePropertyMixinClass } from '@vaadin/vaadin-themable-mixin/vaadin-theme-property-mixin.js';
 import type { ComboBoxBaseMixinClass } from './vaadin-combo-box-base-mixin.js';
 import type { ComboBoxDataProviderMixinClass } from './vaadin-combo-box-data-provider-mixin.js';
+import type { ComboBoxItemsMixinClass } from './vaadin-combo-box-items-mixin.js';
 import type { ComboBoxMixinClass } from './vaadin-combo-box-mixin.js';
 import type { ComboBoxDefaultItem } from './vaadin-combo-box-mixin.js';
 
@@ -175,33 +175,45 @@ export interface ComboBoxEventMap<TItem> extends HTMLElementEventMap {
  * `--vaadin-combo-box-overlay-width`      | Width of the overlay       | `auto`
  * `--vaadin-combo-box-overlay-max-height` | Max height of the overlay  | `65vh`
  *
- * `<vaadin-combo-box>` provides the same set of shadow DOM parts and state attributes as `<vaadin-text-field>`.
- * See [`<vaadin-text-field>`](#/elements/vaadin-text-field) for the styling documentation.
+ * The following shadow DOM parts are available for styling:
  *
- * In addition to `<vaadin-text-field>` parts, the following parts are available for theming:
+ * Part name            | Description
+ * ---------------------|----------------
+ * `label`              | The label element
+ * `input-field`        | The element that wraps prefix, value and buttons
+ * `field-button`       | Set on both clear and toggle buttons
+ * `clear-button`       | The clear button
+ * `error-message`      | The error message element
+ * `helper-text`        | The helper text element wrapper
+ * `required-indicator` | The `required` state indicator element
+ * `toggle-button`      | The toggle button
+ * `overlay`            | The overlay container
+ * `content`            | The overlay content
+ * `loader`             | The loading indicator shown while loading items
  *
- * Part name       | Description
- * ----------------|----------------
- * `toggle-button` | The toggle button
+ * The following state attributes are available for styling:
  *
- * In addition to `<vaadin-text-field>` state attributes, the following state attributes are available for theming:
- *
- * Attribute | Description | Part name
- * ----------|-------------|------------
- * `opened`  | Set when the combo box dropdown is open | :host
- * `loading` | Set when new items are expected | :host
+ * Attribute            | Description
+ * ---------------------|---------------------------------
+ * `disabled`           | Set when the element is disabled
+ * `has-value`          | Set when the element has a value
+ * `has-label`          | Set when the element has a label
+ * `has-helper`         | Set when the element has helper text or slot
+ * `has-error-message`  | Set when the element has an error message
+ * `has-tooltip`        | Set when the element has a slotted tooltip
+ * `invalid`            | Set when the element is invalid
+ * `focused`            | Set when the element is focused
+ * `focus-ring`         | Set when the element is keyboard focused
+ * `readonly`           | Set when the element is readonly
+ * `opened`             | Set when the overlay is opened
+ * `loading`            | Set when loading items from the data provider
  *
  * ### Internal components
  *
  * In addition to `<vaadin-combo-box>` itself, the following internal
  * components are themable:
  *
- * - `<vaadin-combo-box-overlay>` - has the same API as [`<vaadin-overlay>`](#/elements/vaadin-overlay).
  * - `<vaadin-combo-box-item>` - has the same API as [`<vaadin-item>`](#/elements/vaadin-item).
- * - [`<vaadin-input-container>`](#/elements/vaadin-input-container) - an internal element wrapping the input.
- *
- * Note: the `theme` attribute value set on `<vaadin-combo-box>` is
- * propagated to the internal components listed above.
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
@@ -230,13 +242,13 @@ declare class ComboBox<TItem = ComboBoxDefaultItem> extends HTMLElement {
 
 interface ComboBox<TItem = ComboBoxDefaultItem>
   extends ComboBoxDataProviderMixinClass<TItem>,
+    ComboBoxItemsMixinClass<TItem>,
     ComboBoxMixinClass<TItem>,
     ComboBoxBaseMixinClass,
     ValidateMixinClass,
     PatternMixinClass,
     LabelMixinClass,
     KeyboardMixinClass,
-    OverlayClassMixinClass,
     InputMixinClass,
     ClearButtonMixinClass,
     InputControlMixinClass,

package/src/vaadin-combo-box.js

@@ -20,7 +20,7 @@ import { PatternMixin } from '@vaadin/field-base/src/pattern-mixin.js';
 import { inputFieldShared } from '@vaadin/field-base/src/styles/input-field-shared-styles.js';
 import { LumoInjectionMixin } from '@vaadin/vaadin-themable-mixin/lumo-injection-mixin.js';
 import { ThemableMixin } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
-import { comboBoxStyles } from './styles/vaadin-combo-box-core-styles.js';
+import { comboBoxStyles } from './styles/vaadin-combo-box-base-styles.js';
 import { ComboBoxDataProviderMixin } from './vaadin-combo-box-data-provider-mixin.js';
 import { ComboBoxMixin } from './vaadin-combo-box-mixin.js';
 
@@ -107,33 +107,45 @@ import { ComboBoxMixin } from './vaadin-combo-box-mixin.js';
  * `--vaadin-combo-box-overlay-width`      | Width of the overlay       | `auto`
  * `--vaadin-combo-box-overlay-max-height` | Max height of the overlay  | `65vh`
  *
- * `<vaadin-combo-box>` provides the same set of shadow DOM parts and state attributes as `<vaadin-text-field>`.
- * See [`<vaadin-text-field>`](#/elements/vaadin-text-field) for the styling documentation.
+ * The following shadow DOM parts are available for styling:
  *
- * In addition to `<vaadin-text-field>` parts, the following parts are available for theming:
+ * Part name            | Description
+ * ---------------------|----------------
+ * `label`              | The label element
+ * `input-field`        | The element that wraps prefix, value and buttons
+ * `field-button`       | Set on both clear and toggle buttons
+ * `clear-button`       | The clear button
+ * `error-message`      | The error message element
+ * `helper-text`        | The helper text element wrapper
+ * `required-indicator` | The `required` state indicator element
+ * `toggle-button`      | The toggle button
+ * `overlay`            | The overlay container
+ * `content`            | The overlay content
+ * `loader`             | The loading indicator shown while loading items
  *
- * Part name       | Description
- * ----------------|----------------
- * `toggle-button` | The toggle button
+ * The following state attributes are available for styling:
  *
- * In addition to `<vaadin-text-field>` state attributes, the following state attributes are available for theming:
- *
- * Attribute | Description | Part name
- * ----------|-------------|------------
- * `opened`  | Set when the combo box dropdown is open | :host
- * `loading` | Set when new items are expected | :host
+ * Attribute            | Description
+ * ---------------------|---------------------------------
+ * `disabled`           | Set when the element is disabled
+ * `has-value`          | Set when the element has a value
+ * `has-label`          | Set when the element has a label
+ * `has-helper`         | Set when the element has helper text or slot
+ * `has-error-message`  | Set when the element has an error message
+ * `has-tooltip`        | Set when the element has a slotted tooltip
+ * `invalid`            | Set when the element is invalid
+ * `focused`            | Set when the element is focused
+ * `focus-ring`         | Set when the element is keyboard focused
+ * `readonly`           | Set when the element is readonly
+ * `opened`             | Set when the overlay is opened
+ * `loading`            | Set when loading items from the data provider
  *
  * ### Internal components
  *
  * In addition to `<vaadin-combo-box>` itself, the following internal
  * components are themable:
  *
- * - `<vaadin-combo-box-overlay>` - has the same API as [`<vaadin-overlay>`](#/elements/vaadin-overlay).
  * - `<vaadin-combo-box-item>` - has the same API as [`<vaadin-item>`](#/elements/vaadin-item).
- * - [`<vaadin-input-container>`](#/elements/vaadin-input-container) - an internal element wrapping the input.
- *
- * Note: the `theme` attribute value set on `<vaadin-combo-box>` is
- * propagated to the internal components listed above.
  *
  * See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
  *
@@ -206,8 +218,8 @@ class ComboBox extends ComboBoxDataProviderMixin(
         >
           <slot name="prefix" slot="prefix"></slot>
           <slot name="input"></slot>
-          <div id="clearButton" part="clear-button" slot="suffix" aria-hidden="true"></div>
-          <div id="toggleButton" part="toggle-button" slot="suffix" aria-hidden="true"></div>
+          <div id="clearButton" part="field-button clear-button" slot="suffix" aria-hidden="true"></div>
+          <div id="toggleButton" part="field-button toggle-button" slot="suffix" aria-hidden="true"></div>
         </vaadin-input-container>
 
         <div part="helper-text">
@@ -221,13 +233,17 @@ class ComboBox extends ComboBoxDataProviderMixin(
 
       <vaadin-combo-box-overlay
         id="overlay"
+        exportparts="overlay, content, loader"
         .owner="${this}"
+        .dir="${this.dir}"
         .opened="${this._overlayOpened}"
         ?loading="${this.loading}"
         theme="${ifDefined(this._theme)}"
         .positionTarget="${this._positionTarget}"
         no-vertical-overlap
-      ></vaadin-combo-box-overlay>
+      >
+        <slot name="overlay"></slot>
+      </vaadin-combo-box-overlay>
 
       <slot name="tooltip"></slot>
     `;
@@ -257,6 +273,15 @@ class ComboBox extends ComboBoxDataProviderMixin(
     this._toggleElement = this.$.toggleButton;
   }
 
+  /** @protected */
+  updated(props) {
+    super.updated(props);
+
+    if (props.has('dataProvider') || props.has('value')) {
+      this._warnDataProviderValue(this.dataProvider, this.value);
+    }
+  }
+
   /**
    * Override the method from `InputControlMixin`
    * to stop event propagation to prevent `ComboBoxMixin`
@@ -283,6 +308,22 @@ class ComboBox extends ComboBoxDataProviderMixin(
       super._onHostClick(event);
     }
   }
+
+  /** @private */
+  _warnDataProviderValue(dataProvider, value) {
+    if (dataProvider && value !== '' && (this.selectedItem === undefined || this.selectedItem === null)) {
+      const valueIndex = this.__getItemIndexByValue(this.filteredItems, value);
+      if (valueIndex < 0 || !this._getItemLabel(this.filteredItems[valueIndex])) {
+        console.warn(
+          'Warning: unable to determine the label for the provided `value`. ' +
+            'Nothing to display in the text field. This usually happens when ' +
+            'setting an initial `value` before any items are returned from ' +
+            'the `dataProvider` callback. Consider setting `selectedItem` ' +
+            'instead of `value`',
+        );
+      }
+    }
+  }
 }
 
 defineCustomElement(ComboBox);

package/vaadin-combo-box.js

@@ -1,2 +1,2 @@
-import './theme/lumo/vaadin-combo-box.js';
+import './src/vaadin-combo-box.js';
 export * from './src/vaadin-combo-box.js';