TextField is a component for text editing. It can be used both for working with entity attributes and entering/displaying arbitrary textual information.

Component’s XML-name: textField.


Usage example:

<textField id="nameField"
simple text field

To create a TextField connected to data, use dataContainer and property attributes.

    <instance id="customerDc" class="ui.ex1.entity.Customer">

    <textField dataContainer="customerDc"

In the example above, the screen describes the customerDc data container for Customer entity, which has firstName attribute. The TextField component has a link to the container specified in the dataContainer attribute; property attribute contains the name of the entity attribute that is displayed in the TextField.



If the field is not connected to an entity attribute (the data container and attribute name are not set), you can set the data type using the datatype attribute. It is used to format field values. The attribute value accepts any registered data type in the application metadata.

Typically, TextField uses the following data types:

  • decimal

  • double

  • int

  • long

<textField id="integerField"
           caption="Integer field"/>


If a TextField is linked to an entity attribute (via dataContainer and property), and if the entity attribute has a length parameter defined in the @Column JPA-annotation, then the TextField will limit the maximum length of entered text accordingly.

If a TextField is not linked to an attribute, or if the attribute does not have length value defined, or this value needs to be overridden, then the maximum length of the entered text can be limited using maxLength attribute. The value of "-1" means there are no limitations. For example:

<textField id="shortTextField"


By default, TextField trims spaces at the beginning and at the end of the entered string. For example, if user enters " aaa bbb ", the value of the field returned by the getValue() method and saved to the linked entity attribute will be "aaa bbb". You can disable trimming of spaces by setting the trim attribute to false.

Note that trimming only works when users enter a new value. If the value of the linked attribute already has spaces in it, the spaces will be displayed until user edits the value.

<textField id="trimField"
           caption="Trimmed field"

TextField always returns null instead of an entered empty string. Therefore, with the trim attribute enabled, any string containing spaces only will be converted to null.


Sets value for name attribute in HTML.


Case Conversion

TextField supports automatic case conversion. The caseConvertion attribute can have one of the following values:

  • UPPER - the upper case.

  • LOWER - the lower case.

  • NONE - without conversion (the default value). Use this option to support key-sequence input using IME (for example, for Japanese, Korean or Chinese language).

Data Type Conversion

If the datatype attribute is specified for the field, and the user enters an incorrect value, the default conversion error message appears.

For example, TextField with an Integer data type:

<textField id="integerField"
           caption="Integer field"/>

If you enter a value that cannot be interpreted as an integer number the application will show a default error message.

integer text field

Default error messages are specified in the main localized message pack, for example:

databinding.conversion.error.int = Must be Integer

Also, you can use conversionErrorMessage attribute to specify a custom conversion error message declaratively in the screen XML descriptor, for example:

<textField id="textField"
           conversionErrorMessage="This field can work only with Integers"
           caption="Integer field"/>

or programmatically in the screen controller:

private TextField<Integer> textField;

protected void onInit(InitEvent initEvent) {
    textField.setConversionErrorMessage("This field can work only with Integers");


TextField can be assigned validators. The validator limits user input in addition to what is already done by the datatype.



TextField supports TextChangeListener defined in its parent TextInputField interface. Text change events are processed asynchronously after typing in order not to block the typing.

private TextField<String> shortTextField;
private Label<String> shortTextLabel;

protected void onInit(InitEvent initEvent) {
    shortTextField.addTextChangeListener(event -> {
        int length = event.getText().length();
        shortTextLabel.setValue(length + " of " + shortTextField.getMaxLength());

The TextChangeEventMode defines the way the changes are transmitted to the server to cause a server-side event. There are 3 predefined event modes:

  • LAZY (default) - an event is triggered when there is a pause in editing the text. The length of the pause can be modified with setInputEventTimeout().

  • TIMEOUT - an event is triggered after a timeout period. The length of the timeout can be set with setInputEventTimeout().

  • EAGER - an event is triggered immediately for every change in the text content, typically caused by a key press.

  • BLUR - an event is triggered when the text field loses focus.

The textChangeTimeout attribute modifies how often events are communicated to the application when TextChangeEventMode is LAZY or TIMEOUT.


EnterPressListener allows you to define an action executed when Enter is pressed:

private Notifications notifications;
private TextField<Integer> textField;

protected void onInit(InitEvent initEvent) {

    textField.addEnterPressListener(enterPressEvent ->
                    .withCaption("Enter pressed")



ValueChangeListener is triggered on the value changes when the user finished the text input, for example: after the Enter press or when the component loses focus. An event object of the ValueChangeEvent type is passed to the listener. It has the following methods:

  • getPrevValue() returns the value of the component before the change.

  • getValue() returns the current value of the component.

private TextField<Integer> integerField;

protected void onInit(InitEvent initEvent) {
    integerField.addValueChangeListener(stringValueChangeEvent ->
                    .withCaption("Before: " + stringValueChangeEvent.getPrevValue() +
                            ". After: " + stringValueChangeEvent.getValue())

The origin of the ValueChangeEvent can be tracked using isUserOriginated() method.


You can set predefined styles to the TextField component using the stylename attribute either in the XML descriptor or in the screen controller:

<textField stylename="borderless"
           caption="Borderless field"/>
private TextField<String> styledField;

protected void onInit(InitEvent initEvent) {
  • align-center - align the text inside the field to center.

  • align-right - align the text inside the field to the right.

  • borderless - removes the border and background from the text field.

  • inline-icon - moves the default caption icon inside the text field.


  • You can use the setCursorPosition() method to focus the field and set the cursor position to the specified 0-based index.