Package com.vaadin.flow.component.textfield

Class TextField

java.lang.Object
com.vaadin.flow.component.Component
com.vaadin.flow.component.AbstractField<TextField,String>
com.vaadin.flow.component.AbstractSinglePropertyField<TextField,String>
com.vaadin.flow.component.textfield.TextFieldBase<TextField,String>
com.vaadin.flow.component.textfield.TextField
All Implemented Interfaces:
com.vaadin.flow.component.AttachNotifier, com.vaadin.flow.component.BlurNotifier<TextField>, com.vaadin.flow.component.CompositionNotifier, com.vaadin.flow.component.DetachNotifier, com.vaadin.flow.component.Focusable<TextField>, com.vaadin.flow.component.FocusNotifier<TextField>, com.vaadin.flow.component.HasAriaLabel, com.vaadin.flow.component.HasElement, com.vaadin.flow.component.HasEnabled, com.vaadin.flow.component.HasHelper, com.vaadin.flow.component.HasLabel, com.vaadin.flow.component.HasPlaceholder, com.vaadin.flow.component.HasSize, com.vaadin.flow.component.HasStyle, com.vaadin.flow.component.HasTheme, com.vaadin.flow.component.HasValidation, com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>,String>, com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>,String>, com.vaadin.flow.component.InputNotifier, com.vaadin.flow.component.KeyNotifier, com.vaadin.flow.component.shared.HasAllowedCharPattern, com.vaadin.flow.component.shared.HasClearButton, com.vaadin.flow.component.shared.HasPrefix, com.vaadin.flow.component.shared.HasSuffix, com.vaadin.flow.component.shared.HasThemeVariant<TextFieldVariant>, com.vaadin.flow.component.shared.HasTooltip, com.vaadin.flow.component.shared.HasValidationProperties, com.vaadin.flow.component.shared.InputField<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>,String>, HasAutocapitalize, HasAutocomplete, HasAutocorrect, com.vaadin.flow.data.binder.HasValidator<String>, com.vaadin.flow.data.value.HasValueChangeMode, Serializable
@Tag("vaadin-text-field") @NpmPackage(value="@vaadin/text-field", version="25.0.0-alpha21") @JsModule("@vaadin/text-field/src/vaadin-text-field.js") public class TextField extends TextFieldBase<TextField,String> implements com.vaadin.flow.component.shared.HasAllowedCharPattern, com.vaadin.flow.component.shared.HasThemeVariant<TextFieldVariant>
Text Field allows the user to input and edit text. Prefix and suffix components, such as icons, are also supported.

Validation

Text Field comes with a built-in validation mechanism based on constraints. Validation is triggered whenever the user applies an input change, for example by pressing Enter or blurring the field. Programmatic value changes trigger validation as well. In eager and lazy value change modes, validation is also triggered on every character press with a delay according to the selected mode.

Validation verifies that the value satisfies the specified constraints. If any of the constraints are violated, the component is marked as invalid and an error message is displayed below the input.

The following constraints are supported:

Error messages for constraints can be configured with the TextField.TextFieldI18n object, using the respective properties. If you want to provide a single catch-all error message, you can also use the setErrorMessage(String) method. Note that such an error message will take priority over i18n error messages if both are set.

In addition to validation, constraints may also limit user input. For example, the browser will prevent the user from entering more text than specified by the max length constraint.

For more advanced validation that requires custom rules, you can use Binder. By default, before running custom validators, Binder will also check the component constraints and display error messages from the TextField.TextFieldI18n object. The exception is the required constraint, for which Binder provides its own API, see asRequired().

However, if Binder doesn't fit your needs and you want to implement fully custom validation logic, you can disable the constraint 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 setErrorMessage(String) API.

Author:
Vaadin Ltd
See Also:

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    TextField.TextFieldI18n
    The internationalization properties for TextField.

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

    com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<C extends com.vaadin.flow.component.Component,V>

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

    com.vaadin.flow.component.BlurNotifier.BlurEvent<C extends com.vaadin.flow.component.Component>

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

    com.vaadin.flow.component.FocusNotifier.FocusEvent<C extends com.vaadin.flow.component.Component>

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

    com.vaadin.flow.component.HasValue.ValueChangeEvent<V>, com.vaadin.flow.component.HasValue.ValueChangeListener<E extends com.vaadin.flow.component.HasValue.ValueChangeEvent<?>>

  • Field Summary

    Fields inherited from interface com.vaadin.flow.component.textfield.HasAutocapitalize

    AUTOCAPITALIZE_ATTRIBUTE

    Fields inherited from interface com.vaadin.flow.component.textfield.HasAutocomplete

    AUTOCOMPLETE_ATTRIBUTE

    Fields inherited from interface com.vaadin.flow.component.textfield.HasAutocorrect

    AUTOCORRECT_ATTRIBUTE

    Fields inherited from interface com.vaadin.flow.data.value.HasValueChangeMode

    DEFAULT_CHANGE_TIMEOUT

  • Constructor Summary

    Constructors
    Constructor
    Description
    TextField()
    Constructs an empty TextField.
    TextField(com.vaadin.flow.component.HasValue.ValueChangeListener<? super com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>> listener)
    Constructs an empty TextField with a value change listener.
    TextField(String label)
    Constructs an empty TextField with the given label.
    TextField(String label, com.vaadin.flow.component.HasValue.ValueChangeListener<? super com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>> listener)
    Constructs an empty TextField with a label and a value change listener.
    TextField(String label, String placeholder)
    Constructs an empty TextField with the given label and placeholder text.
    TextField(String label, String initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<? super com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>> listener)
    Constructs an empty TextField with a label,a value change listener and an initial value.
    TextField(String label, String initialValue, String placeholder)
    Constructs a TextField with the given label, an initial value and placeholder text.

  • Method Summary

    Modifier and Type
    Method
    Description
    com.vaadin.flow.data.binder.Validator<String>
    getDefaultValidator()
     
    String
    getEmptyValue()
     
    TextField.TextFieldI18n
    getI18n()
    Gets the internationalization object previously set for this component.
    int
    getMaxLength()
    Gets the maximum number of characters (in Unicode code points) that the user can enter.
    int
    getMinLength()
    Gests the minimum number of characters (in Unicode code points) that the user can enter.
    String
    getPattern()
    Gets the regular expression that the value is checked against during validation.
    String
    getValue()
    Returns the current value of the text field.
    void
    setErrorMessage(String errorMessage)
    void
    setI18n(TextField.TextFieldI18n i18n)
    Sets the internationalization object for this component.
    void
    setManualValidation(boolean enabled)
     
    void
    setMaxLength(int maxLength)
    Sets the maximum number of characters (in Unicode code points) that the user can enter.
    void
    setMinLength(int minLength)
    Sets the minimum number of characters (in Unicode code points) that the user can enter.
    void
    setPattern(String pattern)
    Sets a regular expression for the value to pass during validation.
    void
    setRequiredIndicatorVisible(boolean required)
    Sets whether the user is required to provide a value.
    void
    setValue(String value)
    Sets the value of this text field.
    protected void
    validate()
    Validates the current value against the constraints and sets the invalid property and the errorMessage property based on the result.

    Methods inherited from class com.vaadin.flow.component.textfield.TextFieldBase

    addToInput, addToPrefix, addToSuffix, getAriaLabel, getAriaLabelledBy, getTitle, getValueChangeMode, getValueChangeTimeout, isAutofocus, isAutoselect, isRequired, isRequiredIndicatorVisible, setAriaLabel, setAriaLabelledBy, setAutofocus, setAutoselect, setLabel, setRequired, setTitle, setValueChangeMode, setValueChangeTimeout

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

    getSynchronizationRegistration, hasValidValue, setPresentationValue, setSynchronizedEvent

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

    addValueChangeListener, 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, onAttach, onDetach, 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.CompositionNotifier

    addCompositionEndListener, addCompositionStartListener, addCompositionUpdateListener

    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.textfield.HasAutocapitalize

    getAutocapitalize, setAutocapitalize

    Methods inherited from interface com.vaadin.flow.component.textfield.HasAutocomplete

    getAutocomplete, setAutocomplete

    Methods inherited from interface com.vaadin.flow.component.textfield.HasAutocorrect

    isAutocorrect, setAutocorrect

    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

    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.shared.HasSuffix

    getSuffixComponent, setSuffixComponent

    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, setThemeVariant, setThemeVariants, setThemeVariants

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

    getTooltip, setTooltipMarkdown, setTooltipText

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

    getErrorMessage, isInvalid, setInvalid

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

    addValidationStatusChangeListener

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

    addValueChangeListener, clear, getOptionalValue, isEmpty

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

    isReadOnly, setReadOnly

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

    addInputListener

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

    addKeyDownListener, addKeyDownListener, addKeyPressListener, addKeyPressListener, addKeyUpListener, addKeyUpListener

  • Constructor Details

    • TextField

      public TextField()
      Constructs an empty TextField.

    • TextField

      public TextField(String label)
      Constructs an empty TextField with the given label.
      Parameters:
      label - the text to set as the label

    • TextField

      public TextField(String label, String placeholder)
      Constructs an empty TextField with the given label and placeholder text.
      Parameters:
      label - the text to set as the label
      placeholder - the placeholder text to set

    • TextField

      public TextField(String label, String initialValue, String placeholder)
      Constructs a TextField with the given label, an initial value and placeholder text.
      Parameters:
      label - the text to set as the label
      initialValue - the initial value
      placeholder - the placeholder text to set
      See Also:
      • AbstractField.setValue(Object)
      • HasPlaceholder.setPlaceholder(String)

    • TextField

      public TextField(com.vaadin.flow.component.HasValue.ValueChangeListener<? super com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>> listener)
      Constructs an empty TextField with a value change listener.
      Parameters:
      listener - the value change listener
      See Also:
      • AbstractField.addValueChangeListener(com.vaadin.flow.component.HasValue.ValueChangeListener)

    • TextField

      public TextField(String label, com.vaadin.flow.component.HasValue.ValueChangeListener<? super com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>> listener)
      Constructs an empty TextField with a label and a value change listener.
      Parameters:
      label - the text to set as the label
      listener - the value change listener
      See Also:

    • TextField

      public TextField(String label, String initialValue, com.vaadin.flow.component.HasValue.ValueChangeListener<? super com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>> listener)
      Constructs an empty TextField with a label,a value change listener and an initial value.
      Parameters:
      label - the text to set as the label
      initialValue - the initial value
      listener - the value change listener
      See Also:
      • TextFieldBase.setLabel(String)
      • AbstractField.setValue(Object)
      • AbstractField.addValueChangeListener(com.vaadin.flow.component.HasValue.ValueChangeListener)

  • Method Details

    • setErrorMessage

      public void setErrorMessage(String errorMessage)

      Distinct error messages for different constraints can be configured with the TextField.TextFieldI18n object, using the respective properties. However, note that the error message set with setErrorMessage(String) will take priority and override any i18n error messages if both are set.

      Specified by:
      setErrorMessage in interface com.vaadin.flow.component.HasValidation
      Specified by:
      setErrorMessage in interface com.vaadin.flow.component.shared.HasValidationProperties

    • setRequiredIndicatorVisible

      public void setRequiredIndicatorVisible(boolean required)
      Description copied from class: TextFieldBase
      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 TextFieldBase.setLabel(String).

      Specified by:
      setRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>,String>
      Specified by:
      setRequiredIndicatorVisible in interface com.vaadin.flow.component.HasValueAndElement<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>,String>
      Overrides:
      setRequiredIndicatorVisible in class TextFieldBase<TextField,String>
      Parameters:
      required - true to make the field required, false otherwise
      See Also:

    • setMaxLength

      public void setMaxLength(int maxLength)
      Sets the maximum number of characters (in Unicode code points) that the user can enter. Values with a length exceeding this limit will cause the component to invalidate.

      The maximum length is inclusive.

      Parameters:
      maxLength - the maximum length
      See Also:

    • getMaxLength

      public int getMaxLength()
      Gets the maximum number of characters (in Unicode code points) that the user can enter.
      Returns:
      the maximum length
      See Also:

    • setMinLength

      public void setMinLength(int minLength)
      Sets the minimum number of characters (in Unicode code points) that the user can enter. Values with a length shorter than this limit will cause the component to invalidate.

      The minimum length is inclusive.

      Parameters:
      minLength - the minimum length
      See Also:

    • getMinLength

      public int getMinLength()
      Gests the minimum number of characters (in Unicode code points) that the user can enter.
      Returns:
      the minimum length
      See Also:

    • setPattern

      public void setPattern(String pattern)
      Sets a regular expression for the value to pass during validation. Values that do not match the pattern will cause the component to invalidate.

      The pattern must be a valid JavaScript Regular Expression that matches the entire value, not just some subset.

      Parameters:
      pattern - the new String pattern or null to clear it
      See Also:

    • getPattern

      public String getPattern()
      Gets the regular expression that the value is checked against during validation.
      Returns:
      the pattern or null if not set
      See Also:

    • getEmptyValue

      public String getEmptyValue()
      Specified by:
      getEmptyValue in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>,String>
      Overrides:
      getEmptyValue in class com.vaadin.flow.component.AbstractField<TextField,String>

    • setValue

      public void setValue(String value)
      Sets the value of this text field. If the new value is not equal to getValue(), fires a value change event. Throws NullPointerException, if the value is null.

      Note: Binder will take care of the null conversion when integrates with text field, as long as no new converter is defined.

      Specified by:
      setValue in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>,String>
      Overrides:
      setValue in class com.vaadin.flow.component.AbstractField<TextField,String>
      Parameters:
      value - the new value, not null

    • getValue

      public String getValue()
      Returns the current value of the text field. By default, the empty text field will return an empty string.
      Specified by:
      getValue in interface com.vaadin.flow.component.HasValue<com.vaadin.flow.component.AbstractField.ComponentValueChangeEvent<TextField,String>,String>
      Overrides:
      getValue in class com.vaadin.flow.component.AbstractField<TextField,String>
      Returns:
      the current value.

    • getDefaultValidator

      public com.vaadin.flow.data.binder.Validator<String> getDefaultValidator()
      Specified by:
      getDefaultValidator in interface com.vaadin.flow.data.binder.HasValidator<String>

    • setManualValidation

      public void setManualValidation(boolean enabled)
      Specified by:
      setManualValidation in interface com.vaadin.flow.component.HasValidation

    • 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 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.

    • getI18n

      public TextField.TextFieldI18n 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(TextFieldI18n)

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

    • setI18n

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