Package com.vaadin.flow.component.combobox

Class ComboBox<T>

java.lang.Object

com.vaadin.flow.component.Component

com.vaadin.flow.component.AbstractField<C,T>

com.vaadin.flow.component.AbstractSinglePropertyField<TComponent,TValue>

com.vaadin.flow.component.combobox.ComboBoxBase<ComboBox<T>,T,T>

com.vaadin.flow.component.combobox.ComboBox<T>

Type Parameters:

T - the type of the items to be selectable from the combo box

All Implemented Interfaces:

AttachNotifier, BlurNotifier<ComboBox<T>>, DetachNotifier, Focusable<ComboBox<T>>, FocusNotifier<ComboBox<T>>, HasElement, HasEnabled, HasHelper, HasLabel, HasSize, HasStyle, HasTheme, HasValidation, HasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>, HasValueAndElement<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>, HasAllowedCharPattern, HasClearButton, HasThemeVariant<ComboBoxVariant>, HasTooltip, HasValidator<T>, HasDataView<T,String,ComboBoxDataView<T>>, HasLazyDataView<T,String,ComboBoxLazyDataView<T>>, HasListDataView<T,ComboBoxListDataView<T>>, Serializable

@Tag("vaadin-combo-box")
@NpmPackage(value="@vaadin/polymer-legacy-adapter",version="23.3.2") @NpmPackage(value="@vaadin/combo-box",version="23.3.2") @NpmPackage(value="@vaadin/vaadin-combo-box",version="23.3.2")
@JsModule("@vaadin/polymer-legacy-adapter/style-modules.js") @JsModule("@vaadin/combo-box/src/vaadin-combo-box.js") @JsModule("@vaadin/polymer-legacy-adapter/template-renderer.js") @JsModule("./flow-component-renderer.js") @JsModule("./comboBoxConnector.js")
public class ComboBox<T>
extends ComboBoxBase<ComboBox<T>,T,T>
implements HasThemeVariant<ComboBoxVariant>

Combo Box allows the user to choose a value from a filterable list of options presented in an overlay.

ComboBox supports lazy loading. This means that when using large data sets, items are requested from the server one "page" at a time when the user scrolls down the overlay. The number of items in one page is by default 50, and can be changed with ComboBoxBase.setPageSize(int).

ComboBox can do filtering either in the browser or in the server. When ComboBox has only a relatively small set of items, the filtering will happen in the browser, allowing smooth user-experience. When the size of the data set is larger than the pageSize, the webcomponent doesn't necessarily have all the data available, and it will make requests to the server to handle the filtering. Also, if you have defined custom filtering logic, with eg. ComboBoxBase.setItems(ItemFilter, Collection), filtering will happen in the server. To enable client-side filtering with larger data sets, you can override the pageSize to be bigger than the size of your data set. However, then the full data set will be sent to the client immediately, and you will lose the benefits of lazy loading.

Author:

Vaadin Ltd

See Also:

Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static interface	ComboBox.FetchItemsCallback<T>	A callback method for fetching items.
static interface	ComboBox.ItemFilter<T>	Predicate to check ComboBox items against user typed strings.

Nested classes/interfaces inherited from class com.vaadin.flow.component.combobox.ComboBoxBase

ComboBoxBase.CustomValueSetEvent<TComponent extends ComboBoxBase<TComponent,?,?>>

Nested classes/interfaces inherited from class com.vaadin.flow.component.AbstractField

AbstractField.ComponentValueChangeEvent<C extends Component,V>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.BlurNotifier

BlurNotifier.BlurEvent<C extends Component>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.FocusNotifier

FocusNotifier.FocusEvent<C extends Component>

Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue

HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<E extends HasValue.ValueChangeEvent<?>>

Constructor Summary

Constructors

Constructor	Description
ComboBox()	Default constructor.
ComboBox(int pageSize)	Creates an empty combo box with the defined page size for lazy loading.
ComboBox(HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>> listener)	Constructs a combo box with a value change listener.
ComboBox(String label)	Creates an empty combo box with the defined label.
ComboBox(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>> listener)	Constructs a combo box with the defined label and a value change listener.
ComboBox(String label, HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>> listener, T... items)	Constructs a combo box with the defined label, a value change listener and populated with the items in the array.
ComboBox(String label, Collection<T> items)	Creates a combo box with the defined label and populated with the items in the collection.
ComboBox(String label, T... items)	Creates a combo box with the defined label and populated with the items in the array.

Method Summary

Modifier and Type	Method	Description
void	addThemeVariants(ComboBoxVariant... variants)	Adds theme variants to the component.
protected void	addToPrefix(Component... components)	Deprecated. since v23.3
T	getEmptyValue()	Returns the value that represents an empty value.
String	getPattern()	The pattern to validate the input with
boolean	isPreventInvalidInput()	Deprecated. Since 23.2, this API is deprecated.
protected boolean	isSelected(T item)	Whether the item is currently selected in the combo box.
protected void	refreshValue()	Refresh value / selection of the web component after changes that might affect the presentation / rendering of items
protected void	remove(Component... components)	Deprecated. since v23.3
protected void	removeAll()	Deprecated. since v23.3
void	removeThemeVariants(ComboBoxVariant... variants)	Removes theme variants from the component.
void	setPattern(String pattern)	Sets the pattern with which to validate the input
void	setPreventInvalidInput(boolean preventInvalidInput)	Deprecated. Since 23.2, this API is deprecated in favor of HasAllowedCharPattern.setAllowedCharPattern(String)

Methods inherited from class com.vaadin.flow.component.combobox.ComboBoxBase

addCustomValueSetListener, generateLabel, getDataCommunicator, getDataController, getDataGenerator, getDataProvider, getErrorMessage, getFilter, getGenericDataView, getItemLabelGenerator, getKeyMapper, getLazyDataView, getListDataView, getPageSize, getPlaceholder, getRenderManager, isAllowCustomValue, isAutofocus, isAutoOpen, isInvalid, isOpened, isRequired, onAttach, onDetach, runBeforeClientResponse, setAllowCustomValue, setAutofocus, setAutoOpen, setDataProvider, setDataProvider, setDataProvider, setDataProvider, setDataProvider, setErrorMessage, setFilter, setInvalid, setItemLabelGenerator, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItemsWithFilterConverter, setItemsWithFilterConverter, setOpened, setPageSize, setPlaceholder, setRenderer, setRequired, setRequiredIndicatorVisible, setValue, validate

Methods inherited from class com.vaadin.flow.component.AbstractSinglePropertyField

getSynchronizationRegistration, hasValidValue, setPresentationValue, setSynchronizedEvent

Methods inherited from class com.vaadin.flow.component.AbstractField

addValueChangeListener, getValue, isEmpty, setModelValue, valueEquals

Methods inherited from class com.vaadin.flow.component.Component

addListener, findAncestor, fireEvent, from, get, getChildren, getElement, getEventBus, getId, getListeners, getLocale, getParent, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getTranslation, getUI, hasListener, isAttached, isTemplateMapped, isVisible, onEnabledStateChanged, scrollIntoView, set, setElement, setId, setVisible

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Methods inherited from interface com.vaadin.flow.component.AttachNotifier

addAttachListener

Methods inherited from interface com.vaadin.flow.component.BlurNotifier

addBlurListener

Methods inherited from interface com.vaadin.flow.component.DetachNotifier

addDetachListener

Methods inherited from interface com.vaadin.flow.component.Focusable

addFocusShortcut, blur, focus, getTabIndex, setTabIndex

Methods inherited from interface com.vaadin.flow.component.FocusNotifier

addFocusListener

Methods inherited from interface com.vaadin.flow.component.shared.HasAllowedCharPattern

getAllowedCharPattern, setAllowedCharPattern

Methods inherited from interface com.vaadin.flow.component.shared.HasClearButton

isClearButtonVisible, setClearButtonVisible

Methods inherited from interface com.vaadin.flow.component.HasElement

getElement

Methods inherited from interface com.vaadin.flow.component.HasEnabled

isEnabled, setEnabled

Methods inherited from interface com.vaadin.flow.component.HasHelper

getHelperComponent, getHelperText, setHelperComponent, setHelperText

Methods inherited from interface com.vaadin.flow.component.HasLabel

getLabel, setLabel

Methods inherited from interface com.vaadin.flow.data.provider.HasListDataView

setItems

Methods inherited from interface com.vaadin.flow.component.HasSize

getHeight, getHeightUnit, getMaxHeight, getMaxWidth, getMinHeight, getMinWidth, getWidth, getWidthUnit, setHeight, setHeight, setHeightFull, setMaxHeight, setMaxHeight, setMaxWidth, setMaxWidth, setMinHeight, setMinHeight, setMinWidth, setMinWidth, setSizeFull, setSizeUndefined, setWidth, setWidth, setWidthFull

Methods inherited from interface com.vaadin.flow.component.HasStyle

addClassName, addClassNames, getClassName, getClassNames, getStyle, hasClassName, removeClassName, removeClassNames, setClassName, setClassName

Methods inherited from interface com.vaadin.flow.component.HasTheme

addThemeName, addThemeNames, getThemeName, getThemeNames, hasThemeName, removeThemeName, removeThemeNames, setThemeName, setThemeName

Methods inherited from interface com.vaadin.flow.component.shared.HasTooltip

getTooltip, setTooltipText

Methods inherited from interface com.vaadin.flow.data.binder.HasValidator

addValidationStatusChangeListener, getDefaultValidator

Methods inherited from interface com.vaadin.flow.component.HasValue

clear, getOptionalValue

Methods inherited from interface com.vaadin.flow.component.HasValueAndElement

isReadOnly, isRequiredIndicatorVisible, setReadOnly

Constructor Detail

ComboBox

public ComboBox(int pageSize)

Creates an empty combo box with the defined page size for lazy loading.

The default page size is 50.

The page size is also the largest number of items that can support client-side filtering. If you provide more items than the page size, the component has to fall back to server-side filtering.

Parameters:

pageSize - the amount of items to request at a time for lazy loading

See Also:

ComboBoxBase.setPageSize(int)

ComboBox

public ComboBox()

Default constructor. Creates an empty combo box.

ComboBox

public ComboBox(String label)

Creates an empty combo box with the defined label.

Parameters:

label - the label describing the combo box

See Also:

HasLabel.setLabel(String)

ComboBox

public ComboBox(String label,
                Collection<T> items)

Creates a combo box with the defined label and populated with the items in the collection.

Parameters:

label - the label describing the combo box

items - the items to be shown in the list of the combo box

See Also:

HasLabel.setLabel(String), ComboBoxBase.setItems(Collection)

ComboBox

@SafeVarargs
public ComboBox(String label,
                T... items)

Creates a combo box with the defined label and populated with the items in the array.

Parameters:

label - the label describing the combo box

items - the items to be shown in the list of the combo box

See Also:

HasLabel.setLabel(String), HasListDataView.setItems(Object...)

ComboBox

public ComboBox(HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>> listener)

Constructs a combo box with a value change listener.

Parameters:

listener - the value change listener to add

See Also:

AbstractField.addValueChangeListener(ValueChangeListener)

ComboBox

public ComboBox(String label,
                HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>> listener)

Constructs a combo box with the defined label and a value change listener.

Parameters:

label - the label describing the combo box

listener - the value change listener to add

See Also:

HasLabel.setLabel(String), AbstractField.addValueChangeListener(ValueChangeListener)

ComboBox

@SafeVarargs
public ComboBox(String label,
                HasValue.ValueChangeListener<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>> listener,
                T... items)

Constructs a combo box with the defined label, a value change listener and populated with the items in the array.

Parameters:

label - the label describing the combo box

listener - the value change listener to add

items - the items to be shown in the list of the combo box

See Also:

HasLabel.setLabel(String), AbstractField.addValueChangeListener(ValueChangeListener), HasListDataView.setItems(Object...)

Method Detail

isPreventInvalidInput

@Deprecated
public boolean isPreventInvalidInput()

Deprecated.

Since 23.2, this API is deprecated.

Whether the component should block user input that does not match the configured pattern

Returns:

true if the component should block user input that does not match the configured pattern, false otherwise

setPreventInvalidInput

@Deprecated
public void setPreventInvalidInput(boolean preventInvalidInput)

Deprecated.

Since 23.2, this API is deprecated in favor of HasAllowedCharPattern.setAllowedCharPattern(String)

Sets whether the component should block user input that does not match the configured pattern

Parameters:

preventInvalidInput - true if the component should block user input that does not match the configured pattern, false otherwise

getPattern

public String getPattern()

The pattern to validate the input with

Returns:

the pattern to validate the input with

setPattern

public void setPattern(String pattern)

Sets the pattern with which to validate the input

Parameters:

pattern - the pattern to validate the input with

refreshValue

protected void refreshValue()

Description copied from class: ComboBoxBase

Refresh value / selection of the web component after changes that might affect the presentation / rendering of items

Specified by:

refreshValue in class ComboBoxBase<ComboBox<T>,T,T>

isSelected

protected boolean isSelected(T item)

Description copied from class: ComboBoxBase

Whether the item is currently selected in the combo box.

Specified by:

isSelected in class ComboBoxBase<ComboBox<T>,T,T>

Parameters:

item - the item to check

Returns:

true if the item is selected, false otherwise

getEmptyValue

public T getEmptyValue()

Description copied from interface: HasValue

Returns the value that represents an empty value.

By default HasValue is expected to support null as empty values. Specific implementations might not support this.

Specified by:

getEmptyValue in interface HasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,T>,T>

Overrides:

getEmptyValue in class AbstractField<ComboBox<T>,T>

Returns:

empty value

addThemeVariants

public void addThemeVariants(ComboBoxVariant... variants)

Description copied from interface: HasThemeVariant

Adds theme variants to the component.

Specified by:

addThemeVariants in interface HasThemeVariant<T>

Parameters:

variants - theme variants to add

removeThemeVariants

public void removeThemeVariants(ComboBoxVariant... variants)

Description copied from interface: HasThemeVariant

Removes theme variants from the component.

Specified by:

removeThemeVariants in interface HasThemeVariant<T>

Parameters:

variants - theme variants to remove

addToPrefix

@Deprecated
protected void addToPrefix(Component... components)

Deprecated.

since v23.3

Adds the given components as children of this component at the slot 'prefix'.

Parameters:

components - The components to add.

See Also:

MDN page about slots, Spec website about slots

remove

@Deprecated
protected void remove(Component... components)

Deprecated.

since v23.3

Removes the given child components from this component.

Parameters:

components - The components to remove.

Throws:

IllegalArgumentException - if any of the components is not a child of this component.

removeAll

@Deprecated
protected void removeAll()

Deprecated.

since v23.3

Removes all contents from this component, this includes child components, text content as well as child elements that have been added directly to this component using the Element API.