Package com.vaadin.flow.component.textfield

Class TextArea

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.textfield.TextFieldBase<TextArea,String>

com.vaadin.flow.component.textfield.TextArea

All Implemented Interfaces:

AttachNotifier, BlurNotifier<TextArea>, CompositionNotifier, DetachNotifier, Focusable<TextArea>, FocusNotifier<TextArea>, HasAriaLabel, HasElement, HasEnabled, HasHelper, HasLabel, HasPlaceholder, HasSize, HasStyle, HasTheme, HasValidation, HasValue<AbstractField.ComponentValueChangeEvent<TextArea,String>,String>, HasValueAndElement<AbstractField.ComponentValueChangeEvent<TextArea,String>,String>, InputNotifier, KeyNotifier, HasAllowedCharPattern, HasClearButton, HasClientValidation, HasPrefix, HasSuffix, HasThemeVariant<TextAreaVariant>, HasTooltip, HasValidationProperties, InputField<AbstractField.ComponentValueChangeEvent<TextArea,String>,String>, HasAutocapitalize, HasAutocomplete, HasAutocorrect, HasPrefixAndSuffix, HasValidator<String>, HasValueChangeMode, Serializable

@Tag("vaadin-text-area")
@NpmPackage(value="@vaadin/polymer-legacy-adapter",version="24.9.4") @NpmPackage(value="@vaadin/text-area",version="24.9.4")
@JsModule("@vaadin/polymer-legacy-adapter/style-modules.js") @JsModule("@vaadin/text-area/src/vaadin-text-area.js")
public class TextArea
extends TextFieldBase<TextArea,String>
implements HasAllowedCharPattern, HasThemeVariant<TextAreaVariant>

Text Area is an input field component for multi-line text input. Text Area is typically used for descriptions, comments, and other longer free-form content.

Validation

Text Area 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:

• setRequiredIndicatorVisible(boolean)
• setMinLength(int)
• setMaxLength(int)
• setPattern(String)

Error messages for constraints can be configured with the TextArea.TextAreaI18n 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 TextArea.TextAreaI18n 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:

• Serialized Form

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	TextArea.TextAreaI18n	The internationalization properties for TextArea.

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<?>>

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
TextArea()	Constructs an empty TextArea.
TextArea(HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<TextArea,String>> listener)	Constructs an empty TextArea with a value change listener.
TextArea(String label)	Constructs an empty TextArea with the given label.
TextArea(String label, HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<TextArea,String>> listener)	Constructs an empty TextArea with a label and a value change listener.
TextArea(String label, String placeholder)	Constructs an empty TextArea with the given label and placeholder text.
TextArea(String label, String initialValue, HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<TextArea,String>> listener)	Constructs an empty TextArea with a label, a value change listener and an initial value.
TextArea(String label, String initialValue, String placeholder)	Constructs a TextArea with the given label, an initial value and placeholder text.

Method Summary

Modifier and Type	Method	Description
Validator<String>	getDefaultValidator()	Returns a validator that checks the state of the Value.
String	getEmptyValue()	Returns the value that represents an empty value.
TextArea.TextAreaI18n	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.
Integer	getMaxRows()	Maximum number of rows to expand to before the component starts scrolling.
int	getMinLength()	Gets the minimum number of characters (in Unicode code points) that the user can enter.
int	getMinRows()	The minimum number of rows to show.
String	getPattern()	A regular expression that the value is checked against during validation.
String	getValue()	Returns the current value of the text area.
void	scrollToEnd()	Scrolls the textarea to the end if it has a vertical scrollbar.
void	scrollToStart()	Scrolls the textarea to the start if it has a vertical scrollbar.
void	setErrorMessage(String errorMessage)	Sets a single error message to display for all constraint violations.
void	setI18n(TextArea.TextAreaI18n i18n)	Sets the internationalization object for this component.
void	setManualValidation(boolean enabled)	Sets whether manual validation mode is enabled for the component.
void	setMaxLength(int maxLength)	Sets the maximum number of characters (in Unicode code points) that the user can enter.
void	setMaxRows(Integer maxRows)	Sets the maximum number of rows to expand to before the component starts scrolling.
void	setMinLength(int minLength)	Sets the minimum number of characters (in Unicode code points) that the user can enter.
void	setMinRows(int minRows)	Sets the minimum number of rows to show.
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 area.
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.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.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

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

getTooltip, 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

TextArea

public TextArea()

Constructs an empty TextArea.

TextArea

public TextArea(String label)

Constructs an empty TextArea with the given label.

Parameters:

label - the text to set as the label

TextArea

public TextArea(String label,
 String placeholder)

Constructs an empty TextArea with the given label and placeholder text.

Parameters:

label - the text to set as the label

placeholder - the placeholder text to set

TextArea

public TextArea(String label,
 String initialValue,
 String placeholder)

Constructs a TextArea 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)

TextArea

public TextArea(HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<TextArea,String>> listener)

Constructs an empty TextArea with a value change listener.

Parameters:

listener - the value change listener

See Also:

• AbstractField.addValueChangeListener(com.vaadin.flow.component.HasValue.ValueChangeListener)

TextArea

public TextArea(String label,
 HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<TextArea,String>> listener)

Constructs an empty TextArea with a label and a value change listener.

Parameters:

label - the text to set as the label

listener - the value change listener

See Also:

• TextFieldBase.setLabel(String)
• AbstractField.addValueChangeListener(com.vaadin.flow.component.HasValue.ValueChangeListener)

TextArea

public TextArea(String label,
 String initialValue,
 HasValue.ValueChangeListener<? super AbstractField.ComponentValueChangeEvent<TextArea,String>> listener)

Constructs an empty TextArea 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

scrollToStart

public void scrollToStart()

Scrolls the textarea to the start if it has a vertical scrollbar.

scrollToEnd

public void scrollToEnd()

Scrolls the textarea to the end if it has a vertical scrollbar.

setErrorMessage

public void setErrorMessage(String errorMessage)

Sets a single error message to display for all constraint violations. The error message will only appear when the component is flagged as invalid, either as a result of constraint validation or by the developer through HasValidationProperties.setInvalid(boolean) if manual validation mode is enabled.

Distinct error messages for different constraints can be configured with the TextArea.TextAreaI18n 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 HasValidation

Specified by:

setErrorMessage in interface HasValidationProperties

Parameters:

errorMessage - the error message to set, or null to clear

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 HasValue<AbstractField.ComponentValueChangeEvent<TextArea,String>,String>

Specified by:

setRequiredIndicatorVisible in interface HasValueAndElement<AbstractField.ComponentValueChangeEvent<TextArea,String>,String>

Overrides:

setRequiredIndicatorVisible in class TextFieldBase<TextArea,String>

Parameters:

required - true to make the field required, false otherwise

See Also:

• TextArea.TextAreaI18n.setRequiredErrorMessage(String)

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:

• TextArea.TextAreaI18n.setMaxLengthErrorMessage(String)

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:

• setMaxLength(int)

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:

• TextArea.TextAreaI18n.setMinLengthErrorMessage(String)

getMinLength

public int getMinLength()

Gets the minimum number of characters (in Unicode code points) that the user can enter.

Returns:

the minimum length

See Also:

• setMinLength(int)

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:

• TextArea.TextAreaI18n.setPatternErrorMessage(String)
• https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input#htmlattrdefpattern
• https://html.spec.whatwg.org/multipage/input.html#attr-input-pattern

getPattern

public String getPattern()

A regular expression that the value is checked against during validation.

Returns:

the pattern or null if not set

See Also:

• setPattern(String)

getMinRows

public int getMinRows()

The minimum number of rows to show.

Returns:

the minimum number of rows

setMinRows

public void setMinRows(int minRows)

Sets the minimum number of rows to show. Default is two rows.

Parameters:

minRows - the minimum number of rows to show

getMaxRows

public Integer getMaxRows()

Maximum number of rows to expand to before the component starts scrolling.

Returns:

the maximum number of rows, or null if the maximum has not been set

setMaxRows

public void setMaxRows(Integer maxRows)

Sets the maximum number of rows to expand to before the component starts scrolling. This effectively sets a max-height on the input-field part. By default, the value is null, which means the component grows with the content without constraints.

Parameters:

maxRows - the maximum number of rows, or null to remove the maximum

getEmptyValue

public String 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<TextArea,String>,String>

Overrides:

getEmptyValue in class AbstractField<TextArea,String>

Returns:

empty value

setValue

public void setValue(String value)

Sets the value of this text area. 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 area, as long as no new converter is defined.

Specified by:

setValue in interface HasValue<AbstractField.ComponentValueChangeEvent<TextArea,String>,String>

Overrides:

setValue in class AbstractField<TextArea,String>

Parameters:

value - the new value, not null

getValue

public String getValue()

Returns the current value of the text area. By default, the empty text area will return an empty string.

Specified by:

getValue in interface HasValue<AbstractField.ComponentValueChangeEvent<TextArea,String>,String>

Overrides:

getValue in class AbstractField<TextArea,String>

Returns:

the current value.

getDefaultValidator

public Validator<String> 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<String>

Returns:

state validator

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.

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 TextArea.TextAreaI18n 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(TextAreaI18n)

Returns:

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

setI18n

public void setI18n(TextArea.TextAreaI18n i18n)

Sets the internationalization object for this component.

Parameters:

i18n - the i18n object, not null