textField

textField is an input field for editing text or values of other supported data types.

XML Element

textField

Java Class

TypedTextField

Basics

LIVE DEMO

The following example defines a standard text field and a field with a maximum input length:

<textField id="textField" label="TextField"/>
<textField id="textLengthField" label="MaxLength = 10" maxLength="10"/>

Text Fields with Different Data Types

LIVE DEMO

The textField component is a typed component, which means it enables you to work with input of different data types. You can set its type by binding the component to an entity attribute of certain type or by setting type explicitly using the datatype attribute.

<textField id="stringTextField" label="String"
           datatype="string"/>
<textField id="integerTextField" label="Integer"
           datatype="int"/>
<textField id="doubleTextField" label="Double"
           datatype="double"/>

Additional methods to work with typed values include setTypedValue() and getTypedValue(). These methods are useful when you need to set or retrieve values of specific type, such as Integer or Long.

When processing changes to the component’s values, it is recommended to use TypedValueChangeEvent instead of ComponentValueChangeEvent. This approach ensures that the value is of the correct type and avoids the need for additional type conversions or checks.

Data-aware textField

LIVE DEMO

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

XML
<data>
    <instance id="customerDc"
              class="io.jmix.uisamples.entity.Customer"
              fetchPlan="_local"/>
</data>
<layout>
    <textField id="textField" label="Name"
               dataContainer="customerDc" property="name"/>
    <hbox>
        <span text="Value in the container:"/>
        <span id="spanValue"/>
    </hbox>
</layout>
Java
@ViewComponent
protected InstanceContainer<Customer> customerDc;
@ViewComponent
protected Span spanValue;

@Autowired
protected Metadata metadata;

@Subscribe
protected void onInit(InitEvent event) {
    Customer customer = metadata.create(Customer.class);
    customer.setName("John");
    customerDc.setItem(customer);
}

@Subscribe("textField")
protected void onTextFieldValueChange(TypedValueChangeEvent<TypedTextField<String>, String> changeEvent) {
    spanValue.setText(customerDc.getItem().getName());
}

In the example above, the view describes the departmentDc data container for the Department entity, which has the name attribute. The textField component has a link to the container specified in the dataContainer attribute; the property attribute contains the name of the entity attribute that is displayed in textField.

Value Change Modes

LIVE DEMO

Use valueChangeMode to control when user input updates the server-side value. The example also uses a value-change handler to update helper text as the user types.

XML
<details summaryText="Default value change" opened="true" width="AUTO">
    <textField id="textField" placeholder="Start typing"/>
</details>
<details summaryText="Custom value change" opened="true" width="50%">
    <vbox padding="false">
        <textField id="valueChangeModeTextField" maxLength="140" helperText="0/140"/>
        <radioButtonGroup id="valueChangeModeRadioButtonGroup" label="ValueChangeMode"/>
    </vbox>
</details>
Java
@ViewComponent
protected TypedTextField<String> valueChangeModeTextField;
@ViewComponent
protected JmixRadioButtonGroup<ValueChangeMode> valueChangeModeRadioButtonGroup;

@Autowired
protected Notifications notifications;

@Subscribe
protected void onInit(InitEvent event) {
    ComponentUtils.setItemsMap(valueChangeModeRadioButtonGroup, getValueChangeModeItemsMap());
    valueChangeModeRadioButtonGroup.setValue(ValueChangeMode.ON_CHANGE);
}

@Subscribe("valueChangeModeRadioButtonGroup")
protected void onValueChangeModeRadioButtonValueChange(
        ComponentValueChangeEvent<JmixRadioButtonGroup<ValueChangeMode>, ValueChangeMode> event) {
    valueChangeModeTextField.setValueChangeMode(event.getValue());
}

@Subscribe("textField")
protected void onTextFieldValueChange(TypedValueChangeEvent<TypedTextField<String>, String> event) {
    notifications.show("Text Changed: " + event.getValue());
}

@Subscribe("valueChangeModeTextField")
protected void onValueChangeModeTextFieldValueChange(TypedValueChangeEvent<TypedTextField<String>, String> event) {
    TypedTextField<String> sourceTextField = event.getSource();
    sourceTextField.setHelperText(Strings.nullToEmpty(event.getValue()).length() + "/" + sourceTextField.getMaxLength());
}

protected Map<ValueChangeMode, String> getValueChangeModeItemsMap() {
    return Arrays.stream(ValueChangeMode.values())
            .collect(Collectors.toMap(Function.identity(), mode -> mode.name().replace('_', ' ')));
}

Validation

LIVE DEMO

Add nested validators to check converted field values. The example combines built-in numeric range validators with a custom Spring bean validator.

XML
<textField id="integerTextField" label="Positive TextField"
           helperText="Value must be positive"
           datatype="int">
    <validators>
        <custom bean="uisamples_PositiveIntegerValidator"/>
    </validators>
</textField>
<textField id="doubleTextField" label="Double range validator"
           helperText="Value must be between 1.0 and 100.0"
           datatype="double">
    <validators>
        <doubleMin value="1.0" inclusive="true"/>
        <doubleMax value="100.0" inclusive="true"/>
    </validators>
</textField>
Java
@Override
public void accept(Integer value) {
    if (value != null) {
        if (value <= 0) {
            fireValidationException(
                    messages.getMessage("validation.constraints.positive"),
                    ParamsMap.of("value", value)
            );
        }
    }
}

Theme Variants

Use the themeNames attribute to apply one or more theme variants.

Variant Description Supported By

align-left

Aligns the field value to the left side.

Aura, Lumo

align-center

Centers the field value.

Aura, Lumo

align-right

Aligns the field value to the right side.

Aura, Lumo

align-start

Aligns the field value to the start side, taking the current text direction into account.

Aura

align-end

Aligns the field value to the end side, taking the current text direction into account.

Aura

helper-above-field

Renders the helper text above the field, below the label.

Aura, Lumo

small

Makes the component smaller.

Aura, Lumo

Attributes

The following attributes are specific to textField:

Name Description Default

autoselect

Set to true to always have the field value automatically selected when the field gains focus, false otherwise.

—

clearButtonVisible

Controls whether the field displays a clear button.

false

trimEnabled

If true, the component trims spaces at the beginning and at the end of the entered string.

—

value

Sets the component value.

—

The following shared attributes are supported by textField:

id - alignSelf - allowedCharPattern - ariaLabel - ariaLabelledBy - autocapitalize - autocomplete - autocorrect - autofocus - classNames - colspan - css - dataContainer - datatype - enabled - errorMessage - focusShortcut - height - helperText - label - maxHeight - maxLength - maxWidth - minHeight - minLength - minWidth - pattern - placeholder - property - readOnly - required - requiredMessage - themeNames - title - valueChangeMode - valueChangeTimeout - visible - width

Handlers

The following handlers are specific to textField:

Name Description

validator

Validates the component value.

The following shared handlers are supported by textField:

AttachEvent - BlurEvent - ClientValidatedEvent - ComponentValueChangeEvent - CompositionEndEvent - CompositionStartEvent - CompositionUpdateEvent - DetachEvent - FocusEvent - InputEvent - KeyDownEvent - KeyPressEvent - KeyUpEvent - statusChangeHandler - TypedValueChangeEvent

Elements

A textField can include tooltip, validator, prefix, and suffix as its nested elements.

See Also