Package com.vaadin.flow.component.select

Class Select<T>

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.AbstractField<Select<T>,T>
com.vaadin.flow.component.AbstractSinglePropertyField<Select<T>,T>
com.vaadin.flow.component.select.Select<T>
Type Parameters:
T - the type of the items for the select
All Implemented Interfaces:
AttachNotifier, BlurNotifier<Select<T>>, DetachNotifier, Focusable<Select<T>>, FocusNotifier<Select<T>>, HasAriaLabel, HasComponents, HasElement, HasEnabled, HasHelper, HasLabel, HasPlaceholder, HasSize, HasStyle, HasTheme, HasValidation, HasValue<AbstractField.ComponentValueChangeEvent<Select<T>,T>,T>, HasValueAndElement<AbstractField.ComponentValueChangeEvent<Select<T>,T>,T>, HasPrefix, HasThemeVariant<SelectVariant>, HasTooltip, HasValidationProperties, InputField<AbstractField.ComponentValueChangeEvent<Select<T>,T>,T>, HasItemComponents<T>, HasValidator<T>, HasDataView<T,Void,SelectDataView<T>>, HasListDataView<T,SelectListDataView<T>>, SingleSelect<Select<T>,T>, Serializable
@Tag("vaadin-select") @NpmPackage(value="@vaadin/select", version="25.0.0-beta4") @JsModule("@vaadin/select/src/vaadin-select.js") @JsModule("./selectConnector.js") public class Select<T> extends AbstractSinglePropertyField<Select<T>,T> implements Focusable<Select<T>>, HasAriaLabel, HasDataView<T,Void,SelectDataView<T>>, HasItemComponents<T>, InputField<AbstractField.ComponentValueChangeEvent<Select<T>,T>,T>, HasListDataView<T,SelectListDataView<T>>, HasPrefix, HasThemeVariant<SelectVariant>, HasValidationProperties, HasValidator<T>, SingleSelect<Select<T>,T>, HasPlaceholder
Select allows users to choose a single value from a list of options presented in an overlay. The dropdown can be opened with a click, up/down arrow keys, or by typing the initial character for one of the options.

Validation

Select 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 selecting an item from the dropdown. 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 Select.SelectI18n.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 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:

  • Field Details

  • Constructor Details

  • Method Details

    • getItemRenderer

      public ComponentRenderer<? extends Component,T> getItemRenderer()
      Returns the item component renderer.
      Returns:
      the item renderer or null if none set
      See Also:

    • setRenderer

      public void setRenderer(ComponentRenderer<? extends Component,T> renderer)
      Sets the item renderer for this select group. The renderer is applied to each item to create a component which represents the item option in the select's drop down.

      Default is null which means that the item's Object.toString() method is used and set as the text content of the vaadin item element.

      Parameters:
      renderer - the item renderer, or null to clear

    • setTextRenderer

      public void setTextRenderer(ItemLabelGenerator<T> itemLabelGenerator)
      Convenience setter for creating a TextRenderer from the given function that converts the item to a string.

      NOTE: even though this accepts an ItemLabelGenerator, this is not the same as setItemLabelGenerator(ItemLabelGenerator) which does a different thing.

      Parameters:
      itemLabelGenerator - the function that creates the text content from the item, not null

    • setEmptySelectionAllowed

      public void setEmptySelectionAllowed(boolean emptySelectionAllowed)
      Sets whether the user is allowed to select nothing. When set true a special empty item is shown to the user.

      Default is false. The empty selection item can be customized with setEmptySelectionCaption(String).

      Parameters:
      emptySelectionAllowed - true to allow not selecting anything, false to require selection
      See Also:

    • isEmptySelectionAllowed

      public boolean isEmptySelectionAllowed()
      Returns whether the user is allowed to select nothing.
      Returns:
      true if empty selection is allowed, false otherwise

    • setEmptySelectionCaption

      public void setEmptySelectionCaption(String emptySelectionCaption)
      Sets the empty selection caption when setEmptySelectionAllowed(boolean) has been enabled. The caption is shown for the empty selection item in the drop down.

      When the empty selection item is selected, the select shows the value provided by setItemLabelGenerator(ItemLabelGenerator) for the null item, or the string set with setPlaceholder(String) or an empty string if not placeholder is set.

      Default is an empty string "", which will show the place holder when selected.

      Parameters:
      emptySelectionCaption - the empty selection caption to set, not null
      See Also:

    • getEmptySelectionCaption

      public String getEmptySelectionCaption()

    • getItemEnabledProvider

      public SerializablePredicate<T> getItemEnabledProvider()
      Returns the item enabled predicate.
      Returns:
      the item enabled predicate or null if not set
      See Also:

    • setItemEnabledProvider

      public void setItemEnabledProvider(SerializablePredicate<T> itemEnabledProvider)
      Sets the item enabled predicate for this select. The predicate is applied to each item to determine whether the item should be enabled (true) or disabled (false). Disabled items are displayed as grayed out and the user cannot select them.

      By default is null and all the items are enabled.

      Parameters:
      itemEnabledProvider - the item enable predicate or null to clear

    • getItemLabelGenerator

      public ItemLabelGenerator<T> getItemLabelGenerator()
      Gets the item label generator. It generates the text that is shown in the input part for the item when it has been selected.

      Default is null.

      Returns:
      the item label generator, null if not set

    • setItemLabelGenerator

      public void setItemLabelGenerator(ItemLabelGenerator<T> itemLabelGenerator)
      Sets the item label generator. It generates the text that is shown in the input part for the item when it has been selected.

      Default is null and the text content generated for the item with setRenderer(ComponentRenderer) is used instead.

      Parameters:
      itemLabelGenerator - the item label generator to set, or null to clear

    • setPlaceholder

      public void setPlaceholder(String placeholder)
      Sets the placeholder hint for the user.

      The placeholder will be displayed in the case that there is no item selected, or the selected item has an empty string label, or the selected item has no label and it's DOM content is empty.

      Default value is null.

      Specified by:
      setPlaceholder in interface HasPlaceholder
      Parameters:
      placeholder - the placeholder to set, or null to remove

    • setLabel

      public void setLabel(String label)
      Sets the string for the label element.

      NOTE: the label must be set for the required indicator to be visible.

      Specified by:
      setLabel in interface HasLabel
      Parameters:
      label - string or null to clear it

    • getLabel

      public String getLabel()
      Gets the string for the label element.
      Specified by:
      getLabel in interface HasLabel
      Returns:
      the label string, or null if not set

    • setAriaLabel

      public void setAriaLabel(String ariaLabel)
      Description copied from interface: HasAriaLabel
      Set the aria-label of the component to the given text.

      This method should not be used if HasAriaLabel.setAriaLabelledBy(String) is also used. If both attributes are present, aria-labelledby will take precedence over aria-label.

      Specified by:
      setAriaLabel in interface HasAriaLabel
      Parameters:
      ariaLabel - the aria-label text to set or null to clear

    • getAriaLabel

      public Optional<String> getAriaLabel()
      Description copied from interface: HasAriaLabel
      Gets the aria-label of the component.
      Specified by:
      getAriaLabel in interface HasAriaLabel
      Returns:
      an optional aria-label of the component if no aria-label has been set

    • setAriaLabelledBy

      public void setAriaLabelledBy(String ariaLabelledBy)
      Description copied from interface: HasAriaLabel
      Set the aria-labelledby of the component. The value must be a valid id attribute of another element that labels the component. The label element must be in the same DOM scope of the component, otherwise screen readers may fail to announce the label content properly.

      This method should not be used if HasAriaLabel.setAriaLabel(String) is also used. If both attributes are present, aria-labelledby will take precedence over aria-label.

      Specified by:
      setAriaLabelledBy in interface HasAriaLabel
      Parameters:
      ariaLabelledBy - the string with the id of the element that will be used as label or null to clear

    • getAriaLabelledBy

      public Optional<String> getAriaLabelledBy()
      Description copied from interface: HasAriaLabel
      Gets the aria-labelledby of the component
      Specified by:
      getAriaLabelledBy in interface HasAriaLabel
      Returns:
      an optional aria-labelledby of the component if no aria-labelledby has been set

    • setAutofocus

      public void setAutofocus(boolean autofocus)
      Sets the select to have focus when the page loads.

      Default is false.

      Parameters:
      autofocus - the autofocus to set

    • isAutofocus

      public boolean isAutofocus()
      Gets whether this select has been set to autofocus when the page loads.
      Returns:
      true if set to autofocus, false if not

    • setNoVerticalOverlap

      public void setNoVerticalOverlap(boolean noVerticalOverlap)
      Defines whether the overlay should overlap the input element in the y-axis, or be positioned right above/below it.
      Parameters:
      noVerticalOverlap - whether the overlay should overlap the input element

    • isNoVerticalOverlap

      public boolean isNoVerticalOverlap()
      Returns whether the overlay should overlap the input element
      Returns:
      true if the overlay should overlap the input element, false otherwise

    • setDataProvider

      public void setDataProvider(DataProvider<T,?> dataProvider)
      Sets a generic data provider for the Select to use.

      Use this method when none of the setItems methods are applicable, e.g. when having a data provider with filter that cannot be transformed to DataProvider<T, Void>.

      Parameters:
      dataProvider - DataProvider instance to use, not null

    • getDataProvider

      public DataProvider<T,?> getDataProvider()
      Gets the data provider used by this Select.

      To get information and control over the items in the Select, use either getListDataView() or getGenericDataView() instead.

      Returns:
      the data provider used by this Select

    • setItems

      public SelectDataView<T> setItems(DataProvider<T,Void> dataProvider)
      Description copied from interface: HasDataView
      Set a generic data provider for the component to use and returns the base DataView that provides API to get information on the items.

      This method should be used only when the data provider type is not either ListDataProvider or BackEndDataProvider.

      Specified by:
      setItems in interface HasDataView<T,Void,SelectDataView<T>>
      Parameters:
      dataProvider - DataProvider instance to use, not null
      Returns:
      DataView providing information on the data

    • setItems

      public SelectDataView<T> setItems(InMemoryDataProvider<T> inMemoryDataProvider)
      Description copied from interface: HasDataView
      Sets an in-memory data provider for the component to use

      Note! Using a ListDataProvider instead of a InMemoryDataProvider is recommended to get access to ListDataView API by using HasListDataView.setItems(ListDataProvider).

      Specified by:
      setItems in interface HasDataView<T,Void,SelectDataView<T>>
      Parameters:
      inMemoryDataProvider - InMemoryDataProvider to use, not null
      Returns:
      DataView providing information on the data

    • setItems

      public SelectListDataView<T> setItems(ListDataProvider<T> dataProvider)
      Description copied from interface: HasListDataView
      Sets a ListDataProvider for the component to use and returns a ListDataView that provides information and allows operations on the items.
      Specified by:
      setItems in interface HasListDataView<T,SelectListDataView<T>>
      Parameters:
      dataProvider - ListDataProvider providing items to the component.
      Returns:
      ListDataView providing access to the items

    • getGenericDataView

      public SelectDataView<T> getGenericDataView()
      Gets the generic data view for the Select. This data view should only be used when getListDataView() is not applicable for the underlying data provider.
      Specified by:
      getGenericDataView in interface HasDataView<T,Void,SelectDataView<T>>
      Returns:
      the generic DataView instance implementing Select

    • getListDataView

      public SelectListDataView<T> getListDataView()
      Gets the list data view for the Select. This data view should only be used when the items are in-memory and set with: If the items are not in-memory, an exception is thrown.
      Specified by:
      getListDataView in interface HasListDataView<T,SelectListDataView<T>>
      Returns:
      the list data view that provides access to the data bound to the Select

    • onEnabledStateChanged

      public void onEnabledStateChanged(boolean enabled)
      Description copied from class: Component
      Handle component enable state when the enabled state changes.

      By default this sets or removes the 'disabled' attribute from the element. This can be overridden to have custom handling.

      Overrides:
      onEnabledStateChanged in class Component
      Parameters:
      enabled - the new enabled state of the component

    • setRequiredIndicatorVisible

      public void setRequiredIndicatorVisible(boolean required)
      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 setLabel(String).

      Specified by:
      setRequiredIndicatorVisible in interface HasValue<AbstractField.ComponentValueChangeEvent<Select<T>,T>,T>
      Specified by:
      setRequiredIndicatorVisible in interface HasValueAndElement<AbstractField.ComponentValueChangeEvent<Select<T>,T>,T>
      Parameters:
      required - true to make the field required, false otherwise

    • isRequiredIndicatorVisible

      public boolean isRequiredIndicatorVisible()
      Gets whether the user is required to provide a value.
      Specified by:
      isRequiredIndicatorVisible in interface HasValue<AbstractField.ComponentValueChangeEvent<Select<T>,T>,T>
      Specified by:
      isRequiredIndicatorVisible in interface HasValueAndElement<AbstractField.ComponentValueChangeEvent<Select<T>,T>,T>
      Returns:
      true if the field is required, false otherwise
      See Also:

    • add

      public void add(Component... components)
      Adds the given components as children of this component.

      In case any of the specified components has already been added to another parent, it will be removed from there and added to this one.

      NOTE: If you add a component with the slot attribute set, it will be placed in the light-dom of the vaadin-select instead of the dropdown.

      Specified by:
      add in interface HasComponents
      Parameters:
      components - the components to add

    • addComponents

      public void addComponents(T afterItem, Component... components)
      Description copied from interface: HasItemComponents
      Adds the components after the given item.
      Specified by:
      addComponents in interface HasItemComponents<T>
      Parameters:
      afterItem - item to add components after
      components - components to add after item

    • prependComponents

      public void prependComponents(T beforeItem, Component... components)
      Description copied from interface: HasItemComponents
      Adds the components before the given item.
      Specified by:
      prependComponents in interface HasItemComponents<T>
      Parameters:
      beforeItem - item to add components in front of
      components - components to add before item

    • getItemPosition

      public int getItemPosition(T item)
      Description copied from interface: HasItemComponents
      Gets the index of the child element that represents the given item.
      Specified by:
      getItemPosition in interface HasItemComponents<T>
      Parameters:
      item - the item to look for
      Returns:
      the index of the child element that represents the item, or -1 if the item is not found

    • addComponentAtIndex

      public void addComponentAtIndex(int index, Component component)
      Adds the given component as child of this component at the specific index.

      In case the specified component has already been added to another parent, it will be removed from there and added to this one.

      NOTE: If you add a component with the slot attribute set, it will be placed in the light-dom of the vaadin-select instead of the dropdown.

      Specified by:
      addComponentAtIndex in interface HasComponents
      Parameters:
      index - the index, where the component will be added. The index must be non-negative and may not exceed the children count
      component - the component to add, value should not be null

    • addComponentAsFirst

      public void addComponentAsFirst(Component component)
      Adds the given component as the first child of this component.

      In case the specified component has already been added to another parent, it will be removed from there and added to this one.

      NOTE: If you add a component with the slot attribute set, it will be placed in the light-dom of the vaadin-select instead of the dropdown.

      Specified by:
      addComponentAsFirst in interface HasComponents
      Parameters:
      component - the component to add, value should not be null

    • getChildren

      public Stream<Component> getChildren()
      Description copied from class: Component
      Gets the child components of this component.

      The default implementation finds child components by traversing each child Element tree.

      If the component is injected to a PolymerTemplate using the @Id annotation the getChildren method will only return children added from the server side and will not return any children declared in the template file.

      Overrides:
      getChildren in class Component
      Returns:
      the child components of this component
      See Also:

    • remove

      public void remove(Component... components)
      Removes the given child components from this component.

      NOTE: any component with the slot attribute will be attempted to removed from the light dom of the vaadin-select, instead of inside the options drop down.

      Specified by:
      remove in interface HasComponents
      Parameters:
      components - the components to remove
      Throws:
      IllegalArgumentException - if any of the components is not a child of this component

    • removeAll

      public void removeAll()
      Removes all child components that are not items. To remove all items, reset the data provider or use HasListDataView.setItems(Object[]).

      NOTE: this will remove all non-items from the drop down and any slotted components from vaadin-select's light dom.

      Specified by:
      removeAll in interface HasComponents
      See Also:

    • setOverlayWidth

      public void setOverlayWidth(String width)
      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

      public void setOverlayWidth(float width, Unit unit)
      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.

    • setOpened

      protected void setOpened(boolean opened)
      Set true to open the dropdown overlay.
      Parameters:
      opened - the boolean value to set

    • isOpened

      @Synchronize(property="opened", value="opened-changed") protected boolean isOpened()
      Whether the dropdown is opened or not.
      Returns:
      true if the drop-down is opened, false otherwise

    • hasValidValue

      protected boolean hasValidValue()
      Description copied from class: AbstractSinglePropertyField
      Checks whether the element property has a value that can be converted to the model type. Property changes from the element will be ignored if this method returns false. The default implementation always return true.
      Overrides:
      hasValidValue in class AbstractSinglePropertyField<Select<T>,T>
      Returns:
      true if the element property value can be converted to the model type; otherwise false

    • onAttach

      protected void onAttach(AttachEvent attachEvent)
      Description copied from class: Component
      Called when the component is attached to a UI.

      This method is invoked before the AttachEvent is fired for the component. Make sure to call super.onAttach when overriding this method.

      Overrides:
      onAttach in class Component
      Parameters:
      attachEvent - the attach event

    • valueEquals

      protected boolean valueEquals(T value1, T value2)
      Compares two value instances to each other to determine whether they are equal. Equality is used to determine whether to update internal state and fire an event when AbstractField.setValue(Object) or AbstractField.setModelValue(Object, boolean) is called. Subclasses can override this method to define an alternative comparison method instead of Object.equals(Object).
      Overrides:
      valueEquals in class AbstractField<Select<T>,T>
      Parameters:
      value1 - the first instance
      value2 - the second instance
      Returns:
      true if the instances are equal; otherwise false

    • setManualValidation

      public void setManualValidation(boolean enabled)
      Description copied from interface: HasValidation
      Sets whether manual validation mode is enabled for the component.

      When enabled, the component doesn't perform its built-in constraint validation on value change, blur, and other events. This allows manually controlling the invalid state and error messages using the HasValidation.setInvalid(boolean) and HasValidation.setErrorMessage(String) methods. Manual mode is helpful when there is a need for a totally custom validation logic that cannot be achieved with Binder.

      Example: 

       Field field = new Field();
 field.setManualValidation(true);
 field.addValueChangeListener(event -> {
     if (Objects.equal(event.getValue(), "")) {
         field.setInvalid(true);
         field.setErrorMessage("The field is required.");
     } else {
         field.setInvalid(false);
     }
 });

      For components that don't have built-in validation, the method has no effect.

      Specified by:
      setManualValidation in interface HasValidation
      Parameters:
      enabled - whether to enable manual validation mode.

    • getDefaultValidator

      public Validator<T> getDefaultValidator()
      Description copied from interface: HasValidator
      Returns a validator that checks the state of the Value. This should be overridden for components with internal value conversion or validation, e.g. when the user is providing a string that has to be parsed into a date. An invalid input from user will be exposed to a Binder and can be seen as a validation failure.
      Specified by:
      getDefaultValidator in interface HasValidator<T>
      Returns:
      state validator

    • validate

      protected void validate()
      Validates the current value against the constraints and sets the invalid property and the errorMessage property based on the result. If a custom error message is provided with HasValidationProperties.setErrorMessage(String), it is used. Otherwise, the error message defined in the i18n object is used.

      The method does nothing if the manual validation mode is enabled.

    • addOpenedChangeListener

      protected Registration addOpenedChangeListener(ComponentEventListener<Select.OpenedChangeEvent> listener)
      Adds a listener for opened-changed events fired by the webcomponent.
      Parameters:
      listener - the listener
      Returns:
      a Registration for removing the event listener

    • addInvalidChangeListener

      protected Registration addInvalidChangeListener(ComponentEventListener<Select.InvalidChangeEvent> listener)
      Adds a listener for invalid-changed events fired by the webcomponent.
      Parameters:
      listener - the listener
      Returns:
      a Registration for removing the event listener

    • getI18n

      public Select.SelectI18n 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(SelectI18n)

      Returns:
      the i18n object or null if no i18n object has been set

    • setI18n

      public void setI18n(Select.SelectI18n i18n)
      Sets the internationalization object for this component.
      Parameters:
      i18n - the i18n object, not null