> Markdown version of [Text Field](https://vaadin.com/docs/latest/components/text-field). Section index: [llms.txt](https://vaadin.com/docs/latest/components/llms.txt)

# Text Field

Text Field allows users to enter text. Prefix and suffix components, such as icons, are also supported.

**Lit** — `text-field-basic.ts`

```html
<vaadin-text-field label="Street Address" value="Ruukinkatu 2" clear-button-visible>
  <vaadin-icon slot="prefix" icon="vaadin:map-marker"></vaadin-icon>
</vaadin-text-field>
```

**Flow** — `TextFieldBasic.java`

```java
TextField textField = new TextField();
textField.setLabel("Street Address");
textField.setValue("Ruukinkatu 2");
textField.setClearButtonVisible(true);
textField.setPrefixComponent(VaadinIcon.MAP_MARKER.create());
add(textField);
```

**React** — `text-field-basic.tsx`

```tsx
<TextField label="Street Address" value="Ruukinkatu 2" clearButtonVisible>
  <Icon slot="prefix" icon="vaadin:map-marker" />
</TextField>
```

## <a id="basic-features"></a>Basic Features

The following features, common to most input field components, are supported:

Label

The label is used to identify the input field. It supports plain-text content. In the Lumo theme its length is limited to the width of the field (and truncated with ellipsis), while in the Aura theme labels wrap to multiple lines. [Helpers](#helper) and [Tooltips](#tooltip) can be used to provide additional information that doesn’t fit into the label.

Visible labels are strongly recommended for all input fields. In cases where the built-in label cannot be used, an external element can be associated as the field’s label through the `aria-labelledby` attribute (`setAriaLabelledBy` in Flow). Fields without any visible label should include an invisible label for assistive technologies with the `aria-label` attribute (`setAriaLabel` in Flow).

Helper

Helpers are used to provide additional information that the user may need to enter in the field, such as format requirements or explanations of the field’s purpose below the field.

A [style variant](https://vaadin.com/docs/latest/components/text-field/styling.md#style-variants) is available for rendering the helper above the field.

In addition to plain text, helpers can contain components and HTML elements. However, complex and interactive content is likely to have accessibility issues.

Placeholder

The placeholder is text that’s displayed when the field is empty. Its primary purpose is to provide a short input hint (e.g., the expected format) in situations where a [Helper](#helper) cannot be used.

Placeholders should not be used as a replacement for a visible label. They can be mistaken for a manually entered value. See [Label](#label) for alternatives to the built-in field label.

Tooltip

Tooltips are small text pop-ups displayed on hover, and on keyboard-focus. They can be used to provide additional information about a field. This can be useful in situations where an always visible [Helper](#helper) is not appropriate. Helpers are generally recommended in favor of tooltips, though, as they provide much better discoverability and mobile support. See the [Tooltip](https://vaadin.com/docs/latest/components/tooltip.md) documentation for more information.

Clear Button

The clear button — which is displayed when the field is not empty — clears the field’s current value. Although the button itself is not keyboard focusable, the clear action can be taken with the `Esc` key, when the field has focus. The clear button can be especially useful in search and filter fields, where users often need to clear the value. They’re less useful, however, in regular forms.

Prefix & Suffix

Prefix and suffix elements — rendered at either end of the field — can be used to display units, icons, and similar visual cues to the field’s purpose or format.

Prefix and suffix elements aren’t automatically announced by screen readers as part of the field. Text content (e.g., in a `Span` or `Div`) that should be announced can be associated with the field (new in V25.3) using the `accessible-description-ref` attribute (`setAriaDescribedBy` in Flow). Focusable elements (e.g., buttons) are announced separately when focused.

```html
<vaadin-text-field accessible-description-ref="price-prefix price-suffix">
  <span slot="prefix" id="price-prefix">$</span>
  <span slot="suffix" id="price-suffix">per month</span>
</vaadin-text-field>
```

```java
Span prefix = new Span("$");
prefix.setId("price-prefix");
field.setPrefixComponent(prefix);

Span suffix = new Span("per month");
suffix.setId("price-suffix");
field.setSuffixComponent(suffix);

field.setAriaDescribedBy("price-prefix price-suffix");
```

Associated elements are announced in addition to the field’s helper and error message.

External & Invisible Labels (ARIA)

Visible labels are strongly recommended for all input fields. In situations where the built-in label cannot be used, an external element can be associated as the field’s label through its element `id`. Fields without any visible label should be provided an invisible label for assistive technologies like screen readers.

```html
<!-- Associates external element as label: -->
<label id="external-label">This is the label</label>
<vaadin-text-field accessible-name-ref="external-label">...

<!-- Invisible label for screen readers: -->
<vaadin-text-field accessible-name="This is the label">...
```

```java
// Associates external element as label:
NativeLabel label = new NativeLabel("This is the label");
label.setId("external-label");
field.setAriaLabelledBy("external-label");

// Invisible label for screen readers:
field.setAriaLabel("This is the label");
```

**Lit** — `text-field-basic-features.ts`

```typescript
<vaadin-text-field
  label="Label"
  helper-text="Helper text"
  placeholder="Placeholder"
  clear-button-visible
>
  <vaadin-tooltip slot="tooltip" text="Tooltip text"></vaadin-tooltip>
  <vaadin-icon slot="prefix" icon="vaadin:vaadin-h"></vaadin-icon>
  <span slot="suffix">:)</span>
</vaadin-text-field>
```

**Flow** — `TextFieldBasicFeatures.java`

```java
TextField field = new TextField();
field.setLabel("Label");
field.setHelperText("Helper text");
field.setPlaceholder("Placeholder");
field.setTooltipText("Tooltip text");
field.setClearButtonVisible(true);
field.setPrefixComponent(VaadinIcon.VAADIN_H.create());
field.setSuffixComponent(new Span(":)"));
```

**React** — `text-field-basic-features.tsx`

```tsx
<TextField label="Label" helperText="Helper text" placeholder="Placeholder" clearButtonVisible>
  <Tooltip slot="tooltip" text="Tooltip text" />
  <Icon slot="prefix" icon="vaadin:vaadin-h" />
  <span slot="suffix">:)</span>
</TextField>
```

## <a id="validation"></a>Validation

Text Field provides a validation mechanism based on constraints. Constraints allow you to define criteria that the value must meet to be considered valid. Validation occurs typically when the user initiates a value change, for example by entering input and pressing `Enter`. If the value is invalid, the field is highlighted in red, and an error message appears underneath the input. Certain constraints, however, can proactively prevent users from entering characters that would result in an invalid value.

Below is a list of supported constraints with more detailed information:

Required

Required fields are marked with an indicator next to the label, and become invalid if their value is first entered and then cleared.

An instruction text at the top of the form explaining the required indicator is recommended. The indicator itself can be customized with the `--vaadin-input-field-required-indicator` style property.

Min & Max Length

The minimum and maximum input length value constraints dictate the smallest, and the largest number of characters a field accepts. It triggers a validation error if a value shorter than the minimum length is entered, and limits text entered to the maximum length. They can be used to enforce specific formats, or to cap the value to the length supported by the underlying database schema.

In cases where the length requirements may not be clear to the user, it’s recommended to provide this information, for example by using a Helper.

Pattern

The pattern is a regular expression used to validate the full value entered into the field. Any value that doesn’t match the pattern, invalidates the field.

Allowed Characters

A separate single-character, regular expression can be used to restrict the characters that can be entered into the field. Characters that don’t match the expression are rejected. However, values set programmatically are not subject to this restriction, even if they contain disallowed characters.

The following example demonstrates how to specify these constraints and provide error messages:

**Lit** — `text-field-validation.ts`

```typescript
<vaadin-text-field
  required
  minlength="5"
  maxlength="18"
  pattern="^[+]?[\\(]?[0-9]{3}[\\)]?[\\-]?[0-9]{3}[\\-]?[0-9]{4,6}$"
  allowed-char-pattern="[0-9()+-]"
  label="Phone number"
  helper-text="Format: +(123)456-7890"
  .errorMessage="${this.errorMessage}"
  @validated="${(event: TextFieldValidatedEvent) => {
    const field = event.target as TextField;
    const { validity } = field.inputElement as HTMLInputElement;
    if (validity.valueMissing) {
      this.errorMessage = 'Field is required';
    } else if (validity.tooShort) {
      this.errorMessage = `Minimum length is ${field.minlength} characters`;
    } else if (validity.tooLong) {
      this.errorMessage = `Maximum length is ${field.maxlength} characters`;
    } else if (validity.patternMismatch) {
      this.errorMessage = 'Invalid phone number format';
    } else {
      this.errorMessage = '';
    }
  }}"
></vaadin-text-field>
```

**Flow** — `TextFieldValidation.java`

```java
TextField field = new TextField("Phone number");
field.setRequiredIndicatorVisible(true);
field.setPattern(
        "^[+]?[\\(]?[0-9]{3}[\\)]?[\\-]?[0-9]{3}[\\-]?[0-9]{4,6}$");
field.setAllowedCharPattern("[0-9()+-]");
field.setMinLength(5);
field.setMaxLength(18);

field.setI18n(new TextFieldI18n()
        .setRequiredErrorMessage("Field is required")
        .setMinLengthErrorMessage("Minimum length is 5 characters")
        .setMaxLengthErrorMessage("Maximum length is 18 characters")
        .setPatternErrorMessage("Invalid phone number format"));
```

**React** — `text-field-validation.tsx`

```tsx
<TextField
  required
  minlength={5}
  maxlength={18}
  pattern="^[+]?[\(]?[0-9]{3}[\)]?[\-]?[0-9]{3}[\-]?[0-9]{4,6}$"
  allowedCharPattern="[0-9()+-]"
  label="Phone number"
  helperText="Format: +(123)456-7890"
  errorMessage={errorMessage.value}
  onValidated={(event) => {
    const field = event.target as TextFieldElement;
    const { validity } = field.inputElement as HTMLInputElement;
    if (validity.valueMissing) {
      errorMessage.value = 'Field is required';
    } else if (validity.tooShort) {
      errorMessage.value = `Minimum length is ${field.minlength} characters`;
    } else if (validity.tooLong) {
      errorMessage.value = `Maximum length is ${field.maxlength} characters`;
    } else if (validity.patternMismatch) {
      errorMessage.value = 'Invalid phone number format';
    } else {
      errorMessage.value = '';
    }
  }}
/>
```

It’s important to ensure an appropriate error message is configured for each constraint violation to provide users with clear feedback.

> **Note: Data Binding & Custom Validation**
>
> Flow and Hilla offer an advanced API called Binder that allows you to bind data and add custom validation rules for multiple fields, creating forms. You can learn more about Binder from the corresponding [Flow](https://vaadin.com/docs/latest/flow/binding-data/components-binder-validation.md) and [Hilla](https://vaadin.com/docs/latest/hilla/guides/forms/binder-validation.md) articles.

## <a id="read-only-disabled"></a>Read-Only & Disabled

Fields used to display values should be set to `read-only` mode to prevent editing. Read-only fields are focusable and visible to screen readers. They can display tooltips. Their values can be selected and copied.

Fields that are currently unavailable should be `disabled`. The reduced contrast of disabled fields makes them inappropriate for displaying information. They can’t be focused or display tooltips. They’re invisible to screen readers, and their values cannot be selected and copied.

Disabled fields can be useful in situations where they can become enabled based on some user action. Consider hiding fields entirely if there’s nothing the user can do to make them editable.

**Lit** — `text-field-readonly-and-disabled.ts`

```typescript
<vaadin-text-field readonly label="Read-only" value="Value"></vaadin-text-field>

<vaadin-text-field disabled label="Disabled"></vaadin-text-field>
```

**Flow** — `TextFieldReadonlyAndDisabled.java`

```java
TextField readonlyField = new TextField();
readonlyField.setReadOnly(true);
readonlyField.setLabel("Read-only");
readonlyField.setValue("Value");

TextField disabledField = new TextField();
disabledField.setEnabled(false);
disabledField.setLabel("Disabled");
```

**React** — `text-field-readonly-and-disabled.tsx`

```tsx
<TextField readonly label="Read-only" value="Value" />

<TextField disabled label="Disabled" />
```

## <a id="autoselect"></a>Autoselect

When a field is set to `autoselect`, its content is selected when the field is focused. Use `autoselect` when the user might to want to replace the entire value rather than adjust it.

| Autoselect | Focused with                            | Result                                   |
| ---------- | --------------------------------------- | ---------------------------------------- |
| `ON`       | Pointing device or keyboard navigation. | Content selected.                        |
| `OFF`      | Pointing device.                        | Cursor placed where clicked.             |
| `OFF`      | Keyboard navigation `Tab`               | Cursor at the end of the input value.    |
| `OFF`      | Keyboard navigation `Shift`+`Tab`       | Contents selected\[[1](#_footnotedef_1)] |

## <a id="value-change-modes-flow"></a>Value Change Modes Flow

With the Flow Java API, you can define when client-side value changes are synchronized to the server. The `ValueChangeMode` enum provides the following modes:

| Mode                  | Synchronization timing                                                                                                                                           | Custom timeout interval |
| --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------- |
| `EAGER`               | Synchronizes the value whenever it changes on the client side, for example on each keystroke.                                                                    | No                      |
| `LAZY`                | Synchronizes the value after a defined interval has passed without further changes. If another change occurs before the interval ends, the timeout is restarted. | Yes                     |
| `TIMEOUT`             | Synchronizes the value at defined intervals while the value continues to change.                                                                                 | Yes                     |
| `ON_CHANGE` (default) | Synchronizes the value on the `change` event, when the component value is committed.                                                                             | No                      |

For the modes that support a custom timeout interval, you can change the interval with the `setValueChangeTimeout()` method. The default interval is 400 milliseconds.

**Flow** — `TextFieldValueChangeMode.java`

```java
var textField = new TextField("Text Field");
var modeSelector = new Select<>("Value Change Mode", valueChangeModes);
modeSelector.setValue(textField.getValueChangeMode());
modeSelector.addValueChangeListener(e -> {
    textField.clear();
    textField.setValueChangeMode(e.getValue());
});
var serverSideContent = new Span();
textField.addValueChangeListener(
        e -> serverSideContent.setText(e.getValue()));
```

## <a id="input-mode"></a>Input Mode (new in V25.3)

The input mode is a hint to the browser about which virtual keyboard to display when the user interacts with the field on a mobile device.

**Flow**

```java
textField.setInputMode(InputMode.URL);
```

**Lit**

```html
<vaadin-text-field inputmode="url"></vaadin-text-field>
```

**React**

```tsx
<TextField inputmode="url" />
```

See the [`inputmode`](https://developer.mozilla.org/en-US/docs/Web/HTML/Global_attributes/inputmode) attribute on MDN for the list of supported values.

## <a id="related-components"></a>Related Components

A variety of components are available for different types of input:

| Component                                                                 | Usage Recommendation                                                                         |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| [Text Area](https://vaadin.com/docs/latest/components/text-area.md)       | Free-form multi-line text input, for text longer than can typically fit on a single line.    |
| [Email Field](https://vaadin.com/docs/latest/components/email-field.md)   | For email addresses.                                                                         |
| [Number Field](https://vaadin.com/docs/latest/components/number-field.md) | Allows only numeric input.                                                                   |
| [Password Field](https://vaadin.com/docs/latest/components/text-field.md) | For securely entering passwords.                                                             |
| [Combo Box](https://vaadin.com/docs/latest/components/combo-box.md)       | For selecting from a predefined set of options. Allows filtering and entering custom values. |
| [Date Picker](https://vaadin.com/docs/latest/components/date-picker.md)   | Input field for entering or selecting a specific date.                                       |
| [Time Picker](https://vaadin.com/docs/latest/components/time-picker.md)   | Input field for entering or selecting a specific time.                                       |

`E6D6D93F-BDB7-425A-AE47-343981004746`

---

[1](#_footnoteref_1). Consequent keyboard navigation results in the contents being selected until the selection is changed, by either arrow navigation or mouse click.