com.vaadin.flow.component.combobox.
Class 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>>
, HasAriaLabel
, HasElement
, HasEnabled
, HasHelper
, HasLabel
, HasPlaceholder
, HasSize
, HasStyle
, HasTheme
, HasValidation
, HasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,
, HasValueAndElement<AbstractField.ComponentValueChangeEvent<ComboBox<T>,
, HasAllowedCharPattern
, HasAutoOpen
, HasClearButton
, HasClientValidation
, HasOverlayClassName
, HasPrefix
, HasThemeVariant<ComboBoxVariant>
, HasTooltip
, HasValidationProperties
, InputField<AbstractField.ComponentValueChangeEvent<ComboBox<T>,
, HasValidator<T>
, HasDataView<T,
, HasLazyDataView<T,
, HasListDataView<T,
, Serializable
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.
Validation
Combo Box comes with a built-in validation mechanism that verifies that the
field is not empty when required
is enabled.
Validation is triggered whenever the user initiates a value change, for example by selection from the dropdown or manual entry followed by Enter or blur. Programmatic value changes trigger validation as well. If validation fails, the component is marked as invalid and an error message is displayed below the input.
The required error message can be configured using either
ComboBox.ComboBoxI18n.setRequiredErrorMessage(String)
or
HasValidationProperties.setErrorMessage(String)
.
For more advanced validation that requires custom rules, you can use
Binder
. Please note that Binder provides its own API for the required
validation, see asRequired()
.
However, if Binder doesn't fit your needs and you want to implement fully
custom validation logic, you can disable the built-in validation by setting
ComboBoxBase.setManualValidation(boolean)
to true. This will allow you to control
the invalid state and the error message manually using
HasValidationProperties.setInvalid(boolean)
and HasValidationProperties.setErrorMessage(String)
API.
Author:
Vaadin Ltd
See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
The internationalization properties for
ComboBox
.static interface
A callback method for fetching items.
static interface
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,
?, ?>>, ComboBoxBase.SpringData 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.shared.HasClientValidation
HasClientValidation.ClientValidatedEvent
Nested classes/interfaces inherited from interface com.vaadin.flow.component.HasValue
HasValue.ValueChangeEvent<V>, HasValue.ValueChangeListener<E extends HasValue.ValueChangeEvent<?>>
-
Constructor Summary
ConstructorsConstructorDescriptionComboBox()
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.
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.
Creates a combo box with the defined label and populated with the items in the array.
-
Method Summary
Modifier and TypeMethodDescriptionReturns the value that represents an empty value.
getI18n()
Gets the internationalization object previously set for this component.
The pattern to validate the input with
protected boolean
isSelected
(T item) Whether the item is currently selected in the combo box.
protected void
Refresh value / selection of the web component after changes that might affect the presentation / rendering of items
void
setI18n
(ComboBox.ComboBoxI18n i18n) Sets the internationalization object for this component.
void
setOverlayWidth
(float width, Unit unit) Sets the dropdown overlay width.
void
setOverlayWidth
(String width) Sets the dropdown overlay width.
void
setPattern
(String pattern) Sets the pattern with which to validate the input
void
setRequiredIndicatorVisible
(boolean required) Sets whether the user is required to provide a value.
Methods inherited from class com.vaadin.flow.component.combobox.ComboBoxBase
addCustomValueSetListener, generateClassName, generateLabel, getAriaLabel, getAriaLabelledBy, getDataCommunicator, getDataController, getDataGenerator, getDataProvider, getDefaultValidator, getFilter, getGenericDataView, getItemClassNameGenerator, getItemLabelGenerator, getKeyMapper, getLazyDataView, getListDataView, getPageSize, getRenderManager, isAllowCustomValue, isAutofocus, isOpened, isRequired, isRequiredIndicatorVisible, onAttach, onDetach, runBeforeClientResponse, setAllowCustomValue, setAriaLabel, setAriaLabelledBy, setAutofocus, setClassNameGenerator, setDataProvider, setDataProvider, setFilter, setI18n, setItemLabelGenerator, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItems, setItemsPageable, setItemsPageable, setItemsWithFilterConverter, setItemsWithFilterConverter, setManualValidation, setOpened, setPageSize, setRenderer, setRequired, 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, removeFromParent, scrollIntoView, 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.HasAutoOpen
isAutoOpen, setAutoOpen
Methods inherited from interface com.vaadin.flow.component.shared.HasClearButton
isClearButtonVisible, setClearButtonVisible
Methods inherited from interface com.vaadin.flow.component.shared.HasClientValidation
addClientValidatedEventListener
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.data.provider.HasListDataView
setItems
Methods inherited from interface com.vaadin.flow.component.shared.HasOverlayClassName
getOverlayClassName, setOverlayClassName
Methods inherited from interface com.vaadin.flow.component.HasPlaceholder
getPlaceholder, setPlaceholder
Methods inherited from interface com.vaadin.flow.component.shared.HasPrefix
getPrefixComponent, setPrefixComponent
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.HasThemeVariant
addThemeVariants, removeThemeVariants
Methods inherited from interface com.vaadin.flow.component.shared.HasTooltip
getTooltip, setTooltipText
Methods inherited from interface com.vaadin.flow.component.shared.HasValidationProperties
getErrorMessage, isInvalid, setErrorMessage, setInvalid
Methods inherited from interface com.vaadin.flow.data.binder.HasValidator
addValidationStatusChangeListener
Methods inherited from interface com.vaadin.flow.component.HasValue
addValueChangeListener, clear, getOptionalValue, getValue, isEmpty
Methods inherited from interface com.vaadin.flow.component.HasValueAndElement
isReadOnly, setReadOnly
-
Constructor Details
-
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 loadingSee Also:
-
ComboBox
public ComboBox()Default constructor. Creates an empty combo box.
-
ComboBox
Creates an empty combo box with the defined label.
Parameters:
label
- the label describing the combo boxSee Also:
-
ComboBox
Creates a combo box with the defined label and populated with the items in the collection.
Parameters:
label
- the label describing the combo boxitems
- the items to be shown in the list of the combo boxSee Also:
-
ComboBox
Creates a combo box with the defined label and populated with the items in the array.
Parameters:
label
- the label describing the combo boxitems
- the items to be shown in the list of the combo boxSee Also:
-
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 addSee Also:
-
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 boxlistener
- the value change listener to addSee Also:
-
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 boxlistener
- the value change listener to additems
- the items to be shown in the list of the combo boxSee Also:
-
-
Method Details
-
setRequiredIndicatorVisible
public void setRequiredIndicatorVisible(boolean required) Description copied from class:
ComboBoxBase
Sets whether the user is required to provide a value. When required, an indicator appears next to the label and the field invalidates if the value is cleared.
NOTE: The required indicator is only visible when the field has a label, see
HasLabel.setLabel(String)
.Specified by:
setRequiredIndicatorVisible
in interfaceHasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,
T>, T> Specified by:
setRequiredIndicatorVisible
in interfaceHasValueAndElement<AbstractField.ComponentValueChangeEvent<ComboBox<T>,
T>, T> Overrides:
setRequiredIndicatorVisible
in classComboBoxBase<ComboBox<T>,
T, T> Parameters:
required
-true
to make the field required,false
otherwiseSee Also:
-
getPattern
The pattern to validate the input with
Returns:
the pattern to validate the input with
-
setPattern
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 classComboBoxBase<ComboBox<T>,
T, T> -
isSelected
Description copied from class:
ComboBoxBase
Whether the item is currently selected in the combo box.
Specified by:
isSelected
in classComboBoxBase<ComboBox<T>,
T, T> Parameters:
item
- the item to checkReturns:
true
if the item is selected,false
otherwise -
getEmptyValue
Description copied from interface:
HasValue
Returns the value that represents an empty value.
By default
HasValue
is expected to supportnull
as empty values. Specific implementations might not support this.Specified by:
getEmptyValue
in interfaceHasValue<AbstractField.ComponentValueChangeEvent<ComboBox<T>,
T>, T> Overrides:
getEmptyValue
in classAbstractField<ComboBox<T>,
T> Returns:
empty value
-
setOverlayWidth
Sets the dropdown overlay width.
Parameters:
width
- the new dropdown width. Pass in null to set the dropdown width back to the default value. -
setOverlayWidth
Sets the dropdown overlay width. Negative number implies unspecified size (the dropdown width is reverted back to the default value).
Parameters:
width
- the width of the dropdown.unit
- the unit used for the dropdown. -
getI18n
Gets the internationalization object previously set for this component.
NOTE: Updating the instance that is returned from this method will not update the component if not set again using
setI18n(ComboBoxI18n)
-
setI18n
Sets the internationalization object for this component.
Parameters:
i18n
- the i18n object, notnull
-