combo-boxpackage.src.vaadin-combo-box.d.ts Maven / Gradle / Ivy
Go to download
Show more of this group Show more artifacts with this name
Show all versions of vaadin-webcomponents Show documentation
Show all versions of vaadin-webcomponents Show documentation
Mvnpm composite: Vaadin webcomponents
The newest version!
/**
* @license
* Copyright (c) 2015 - 2024 Vaadin Ltd.
* This program is available under Apache License Version 2.0, available at https://vaadin.com/license/
*/
import type { DelegateFocusMixinClass } from '@vaadin/a11y-base/src/delegate-focus-mixin.js';
import type { DisabledMixinClass } from '@vaadin/a11y-base/src/disabled-mixin.js';
import type { FocusMixinClass } from '@vaadin/a11y-base/src/focus-mixin.js';
import type { KeyboardMixinClass } from '@vaadin/a11y-base/src/keyboard-mixin.js';
import type { ControllerMixinClass } from '@vaadin/component-base/src/controller-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';
import type { InputControlMixinClass } from '@vaadin/field-base/src/input-control-mixin.js';
import type { InputMixinClass } from '@vaadin/field-base/src/input-mixin.js';
import type { LabelMixinClass } from '@vaadin/field-base/src/label-mixin.js';
import type { PatternMixinClass } from '@vaadin/field-base/src/pattern-mixin.js';
import type { ValidateMixinClass } from '@vaadin/field-base/src/validate-mixin.js';
import type { ThemableMixinClass } from '@vaadin/vaadin-themable-mixin/vaadin-themable-mixin.js';
import type { ThemePropertyMixinClass } from '@vaadin/vaadin-themable-mixin/vaadin-theme-property-mixin.js';
import type { ComboBoxDataProviderMixinClass } from './vaadin-combo-box-data-provider-mixin.js';
import type { ComboBoxMixinClass } from './vaadin-combo-box-mixin.js';
import type { ComboBoxDefaultItem } from './vaadin-combo-box-mixin.js';
export {
ComboBoxDataProvider,
ComboBoxDataProviderCallback,
ComboBoxDataProviderParams,
} from './vaadin-combo-box-data-provider-mixin.js';
export { ComboBoxDefaultItem, ComboBoxItemModel, ComboBoxRenderer } from './vaadin-combo-box-mixin.js';
/**
* Fired when the user commits a value change.
*/
export type ComboBoxChangeEvent = Event & {
target: ComboBox;
};
/**
* Fired when the user sets a custom value.
*/
export type ComboBoxCustomValueSetEvent = CustomEvent;
/**
* Fired when the `opened` property changes.
*/
export type ComboBoxOpenedChangedEvent = CustomEvent<{ value: boolean }>;
/**
* Fired when the `invalid` property changes.
*/
export type ComboBoxInvalidChangedEvent = CustomEvent<{ value: boolean }>;
/**
* Fired when the `value` property changes.
*/
export type ComboBoxValueChangedEvent = CustomEvent<{ value: string }>;
/**
* Fired when the `filter` property changes.
*/
export type ComboBoxFilterChangedEvent = CustomEvent<{ value: string }>;
/**
* Fired when the `selectedItem` property changes.
*/
export type ComboBoxSelectedItemChangedEvent = CustomEvent<{ value: TItem | null | undefined }>;
/**
* Fired whenever the field is validated.
*/
export type ComboBoxValidatedEvent = CustomEvent<{ valid: boolean }>;
export interface ComboBoxEventMap extends HTMLElementEventMap {
change: ComboBoxChangeEvent;
'custom-value-set': ComboBoxCustomValueSetEvent;
'opened-changed': ComboBoxOpenedChangedEvent;
'filter-changed': ComboBoxFilterChangedEvent;
'invalid-changed': ComboBoxInvalidChangedEvent;
'value-changed': ComboBoxValueChangedEvent;
'selected-item-changed': ComboBoxSelectedItemChangedEvent;
validated: ComboBoxValidatedEvent;
}
/**
* `` is a web component for choosing a value from a filterable list of options
* presented in a dropdown overlay. The options can be provided as a list of strings or objects
* by setting [`items`](#/elements/vaadin-combo-box#property-items) property on the element.
*
* ```html
* ` elements placed in the dropdown, use
* [`renderer`](#/elements/vaadin-combo-box#property-renderer) property which accepts a function.
* The renderer function is called with `root`, `comboBox`, and `model` as arguments.
*
* Generate DOM content by using `model` object properties if needed, and append it to the `root`
* element. The `comboBox` reference is provided to access the combo-box element state. Do not
* set combo-box properties in a `renderer` function.
*
* ```js
* const comboBox = document.querySelector('#combo-box');
* comboBox.items = [{'label': 'Hydrogen', 'value': 'H'}];
* comboBox.renderer = (root, comboBox, model) => {
* const item = model.item;
* root.innerHTML = `${model.index}: ${item.label} ${item.value}`;
* };
* ```
*
* Renderer is called on the opening of the combo-box and each time the related model is updated.
* Before creating new content, it is recommended to check if there is already an existing DOM
* element in `root` from a previous renderer call for reusing it. Even though combo-box uses
* infinite scrolling, reducing DOM operations might improve performance.
*
* The following properties are available in the `model` argument:
*
* Property | Type | Description
* -----------|------------------|-------------
* `index` | Number | Index of the item in the `items` array
* `item` | String or Object | The item reference
* `selected` | Boolean | True when item is selected
* `focused` | Boolean | True when item is focused
*
* ### Lazy Loading with Function Data Provider
*
* In addition to assigning an array to the items property, you can alternatively use the
* [`dataProvider`](#/elements/vaadin-combo-box#property-dataProvider) function property.
* The `` calls this function lazily, only when it needs more data
* to be displayed.
*
* __Note that when using function data providers, the total number of items
* needs to be set manually. The total number of items can be returned
* in the second argument of the data provider callback:__
*
* ```js
* comboBox.dataProvider = async (params, callback) => {
* const API = 'https://demo.vaadin.com/demo-data/1.0/filtered-countries';
* const { filter, page, pageSize } = params;
* const index = page * pageSize;
*
* const res = await fetch(`${API}?index=${index}&count=${pageSize}&filter=${filter}`);
* if (res.ok) {
* const { result, size } = await res.json();
* callback(result, size);
* }
* };
* ```
*
* ### Styling
*
* The following custom properties are available for styling:
*
* Custom property | Description | Default
* ----------------------------------------|----------------------------|---------
* `--vaadin-field-default-width` | Default width of the field | `12em`
* `--vaadin-combo-box-overlay-width` | Width of the overlay | `auto`
* `--vaadin-combo-box-overlay-max-height` | Max height of the overlay | `65vh`
*
* `` provides the same set of shadow DOM parts and state attributes as ``.
* See [``](#/elements/vaadin-text-field) for the styling documentation.
*
* In addition to `` parts, the following parts are available for theming:
*
* Part name | Description
* ----------------|----------------
* `toggle-button` | The toggle button
*
* In addition to `` 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
*
* If you want to replace the default `` and its container with a custom implementation to get full control
* over the input field, consider using the [``](#/elements/vaadin-combo-box-light) element.
*
* ### Internal components
*
* In addition to `` itself, the following internal
* components are themable:
*
* - `` - has the same API as [``](#/elements/vaadin-overlay).
* - `` - has the same API as [``](#/elements/vaadin-item).
* - [``](#/elements/vaadin-input-container) - an internal element wrapping the input.
*
* Note: the `theme` attribute value set on `` is
* propagated to the internal components listed above.
*
* See [Styling Components](https://vaadin.com/docs/latest/styling/styling-components) documentation.
*
* @fires {Event} change - Fired when the user commits a value change.
* @fires {CustomEvent} custom-value-set - Fired when the user sets a custom value.
* @fires {CustomEvent} filter-changed - Fired when the `filter` property changes.
* @fires {CustomEvent} invalid-changed - Fired when the `invalid` property changes.
* @fires {CustomEvent} opened-changed - Fired when the `opened` property changes.
* @fires {CustomEvent} selected-item-changed - Fired when the `selectedItem` property changes.
* @fires {CustomEvent} value-changed - Fired when the `value` property changes.
* @fires {CustomEvent} validated - Fired whenever the field is validated.
*/
declare class ComboBox extends HTMLElement {
addEventListener>(
type: K,
listener: (this: ComboBox, ev: ComboBoxEventMap[K]) => void,
options?: AddEventListenerOptions | boolean,
): void;
removeEventListener>(
type: K,
listener: (this: ComboBox, ev: ComboBoxEventMap[K]) => void,
options?: EventListenerOptions | boolean,
): void;
}
interface ComboBox
extends ComboBoxDataProviderMixinClass,
ComboBoxMixinClass,
ValidateMixinClass,
PatternMixinClass,
LabelMixinClass,
KeyboardMixinClass,
OverlayClassMixinClass,
InputMixinClass,
ClearButtonMixinClass,
InputControlMixinClass,
InputConstraintsMixinClass,
FocusMixinClass,
FieldMixinClass,
DisabledMixinClass,
DelegateStateMixinClass,
DelegateFocusMixinClass,
ThemableMixinClass,
ThemePropertyMixinClass,
ElementMixinClass,
ControllerMixinClass {}
declare global {
interface HTMLElementTagNameMap {
'vaadin-combo-box': ComboBox;
}
}
export { ComboBox };