5.8. TextField

TextField is one of the most commonly used user interface components. It is a Field component that allows entering textual values using keyboard.

The following example creates a simple text field:

// Create a text field
TextField tf = new TextField("A Field");
// Put some initial content in it
tf.setValue("Stuff in the field");

See the result in Figure 5.20, “TextField Example”.

Figure 5.20. TextField Example

TextField Example

Value changes are handled with a Property.ValueChangeListener, as in most other fields. The value can be acquired with getValue() directly from the text field, as is done in the example below, or from the property reference of the event.

// Handle changes in the value
tf.addValueChangeListener(new Property.ValueChangeListener() {
    private static final long serialVersionUID = -6549081726526133772L;

    public void valueChange(ValueChangeEvent event) {
        // Assuming that the value type is a String
        String value = (String) event.getProperty().getValue();

        // Do something with the value
        Notification.show("Value is: " + value);

// Fire value changes immediately when the field loses focus

Much of the API of TextField is defined in AbstractTextField, which allows different kinds of text input fields, such as rich text editors, which do not share all the features of the single-line text fields.

Figure 5.21. Text Field Class Relationships

Text Field Class Relationships

5.8.1. Data Binding

TextField edits String values, but you can bind it to any property type that has a proper converter, as described in Section 9.2.3, “Converting Between Property Type and Representation”.

// Have an initial data model. As Double is unmodificable and
// doesn't support assignment from String, the object is
// reconstructed in the wrapper when the value is changed.
Double trouble = 42.0;
// Wrap it in a property data source
final ObjectProperty<Double> property =
    new ObjectProperty<Double>(trouble);
// Create a text field bound to it
// (StringToDoubleConverter is used automatically)
TextField tf = new TextField("The Answer", property);

// Show that the value is really written back to the
// data source when edited by user.
Label feedback = new Label(property);
feedback.setCaption("The Value");

When you put a Table in editable mode or create fields with a FieldGroup, the DefaultFieldFactory creates a TextField for almost every property type by default. You often need to make a custom factory to customize the creation and to set the field tooltip, validation, formatting, and so on.

See Chapter 9, Binding Components to Data for more details on data binding, field factories for Table in Section 5.16.3, “Editing the Values in a Table”, and Section 9.4, “Creating Forms by Binding Fields to Items” regarding forms.

5.8.2. String Length

The setMaxLength() method sets the maximum length of the input string so that the browser prevents the user from entering a longer one. As a security feature, the input value is automatically truncated on the server-side, as the maximum length setting could be bypassed on the client-side. The maximum length property is defined at AbstractTextField level.

Notice that the maximum length setting does not affect the width of the field. You can set the width with setWidth(), as with other components. Using em widths is recommended to better approximate the proper width in relation to the size of the used font. There is no standard way in HTML for setting the width exactly to a number of letters (in a monospaced font). You can trick your way around this restriction by putting the text field in an undefined-width VerticalLayout together with an undefined-width Label that contains a sample text, and setting the width of the text field as 100%. The layout will get its width from the label, and the text field will use that.

5.8.3. Handling Null Values

As with any field, the value of a TextField can be set as null. This occurs most commonly when you create a new field without setting a value for it or bind the field value to a data source that allows null values. In such case, you might want to show a special value that stands for the null value. You can set the null representation with the setNullRepresentation() method. Most typically, you use an empty string for the null representation, unless you want to differentiate from a string that is explicitly empty. The default null representation is "null", which essentially warns that you may have forgotten to initialize your data objects properly.

The setNullSettingAllowed() controls whether the user can actually input a null value by using the null value representation. If the setting is false, which is the default, inputting the null value representation string sets the value as the literal value of the string, not null. This default assumption is a safeguard for data sources that may not allow null values.

// Create a text field without setting its value
TextField tf = new TextField("Field Energy (J)");
tf.setNullRepresentation("-- null-point energy --");

// The null value is actually the default
// Allow user to input the null value by
// its representation

// Feedback to see the value
Label value = new Label(tf);
value.setCaption("Current Value:");

The Label, which is bound to the value of the TextField, displays a null value as empty. The resulting user interface is shown in Figure 5.22, “Null Value Representation”.

Figure 5.22. Null Value Representation

Null Value Representation

5.8.4. Text Change Events

Often you want to receive a change event immediately when the text field value changes. The immediate mode is not literally immediate, as the changes are transmitted only after the field loses focus. In the other extreme, using keyboard events for every keypress would make typing unbearably slow and also processing the keypresses is too complicated for most purposes. Text change events are transmitted asynchronously soon after typing and do not block typing while an event is being processed.

Text change events are received with a TextChangeListener, as is done in the following example that demonstrates how to create a text length counter:

// Text field with maximum length
final TextField tf = new TextField("My Eventful Field");
tf.setValue("Initial content");

// Counter for input length
final Label counter = new Label();
counter.setValue(tf.getValue().length() +
                 " of " + tf.getMaxLength());

// Display the current length interactively in the counter
tf.addTextChangeListener(new TextChangeListener() {
    public void textChange(TextChangeEvent event) {
        int len = event.getText().length();
        counter.setValue(len + " of " + tf.getMaxLength());

// The lazy mode is actually the default

The result is shown in Figure 5.23, “Text Change Events”.

Figure 5.23. Text Change Events

Text Change Events

The text change event mode defines how quickly the changes are transmitted to the server and cause a server-side event. Lazier change events allow sending larger changes in one event if the user is typing fast, thereby reducing server requests.

You can set the text change event mode of a TextField with setTextChangeEventMode(). The allowed modes are defined in TextChangeEventMode enum and are as follows:

TextChangeEventMode.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(). As with the TIMEOUT mode, a text change event is forced before a possible ValueChangeEvent, even if the user did not keep a pause while entering the text.

This is the default mode.


A text change in the user interface causes the event to be communicated to the application after a timeout period. If more changes are made during this period, the event sent to the server-side includes the changes made up to the last change. The length of the timeout can be set with setInputEventTimeout().

If a ValueChangeEvent would occur before the timeout period, a TextChangeEvent is triggered before it, on the condition that the text content has changed since the previous TextChangeEvent.


An event is triggered immediately for every change in the text content, typically caused by a key press. The requests are separate and are processed sequentially one after another. Change events are nevertheless communicated asynchronously to the server, so further input can be typed while event requests are being processed.

5.8.5. CSS Style Rules

.v-textfield { }

The HTML structure of TextField is extremely simple, consisting only of an element with the v-textfield style.

For example, the following custom style uses dashed border:

.v-textfield-dashing {
    border:     thin dashed;
    background: white; /* Has shading image by default */

The result is shown in Figure 5.24, “Styling TextField with CSS”.

Figure 5.24. Styling TextField with CSS

Styling TextField with CSS

The style name for TextField is also used in several components that contain a text input field, even if the text input is not an actual TextField. This ensures that the style of different text input boxes is similar.

I. Introduction
1. Introduction
1.1. Overview
1.2. Example Application Walkthrough
1.3. Support for the Eclipse IDE
1.4. Goals and Philosophy
1.5. Background
2. Getting Started with Vaadin
2.1. Overview
2.2. Setting up the Development Environment
2.3. Overview of Vaadin Libraries
2.4. Installing Vaadin Plugin for Eclipse
2.5. Creating and Running a Project with Eclipse
2.6. Using Vaadin with Maven
2.7. Creating a Project with NetBeans IDE
2.8. Creating a Project with IntelliJ IDEA
2.9. Vaadin Installation Package
2.10. Using Vaadin with Scala
3. Architecture
3.1. Overview
3.2. Technological Background
3.3. Client-Side Engine
3.4. Events and Listeners
II. Server-Side Framework
4. Writing a Server-Side Web Application
4.1. Overview
4.2. Building the UI
4.3. Handling Events with Listeners
4.4. Images and Other Resources
4.5. Handling Errors
4.6. Notifications
4.7. Application Lifecycle
4.8. Deploying an Application
5. User Interface Components
5.1. Overview
5.2. Interfaces and Abstractions
5.3. Common Component Features
5.4. Field Components
5.5. Component Extensions
5.6. Label
5.7. Link
5.8. TextField
5.9. TextArea
5.10. PasswordField
5.11. RichTextArea
5.12. Date and Time Input with DateField
5.13. Button
5.14. CheckBox
5.15. Selecting Items
5.16. Table
5.17. Tree
5.18. MenuBar
5.19. Embedded Resources
5.20. Upload
5.21. ProgressBar
5.22. Slider
5.23. Calendar
5.24. Component Composition with CustomComponent
5.25. Composite Fields with CustomField
6. Managing Layout
6.1. Overview
6.2. UI, Window, and Panel Content
6.3. VerticalLayout and HorizontalLayout
6.4. GridLayout
6.5. FormLayout
6.6. Panel
6.7. Sub-Windows
6.8. HorizontalSplitPanel and VerticalSplitPanel
6.9. TabSheet
6.10. Accordion
6.11. AbsoluteLayout
6.12. CssLayout
6.13. Layout Formatting
6.14. Custom Layouts
7. Visual User Interface Design with Eclipse
7.1. Overview
7.2. Creating a New Composite
7.3. Using The Visual Editor
7.4. Structure of a Visually Editable Component
8. Themes
8.1. Overview
8.2. Introduction to Cascading Style Sheets
8.3. Syntactically Awesome Stylesheets (Sass)
8.4. Creating and Using Themes
8.5. Creating a Theme in Eclipse
8.6. Responsive Themes
9. Binding Components to Data
9.1. Overview
9.2. Properties
9.3. Holding properties in Items
9.4. Creating Forms by Binding Fields to Items
9.5. Collecting Items in Containers
10. Vaadin SQLContainer
10.1. Architecture
10.2. Getting Started with SQLContainer
10.3. Filtering and Sorting
10.4. Editing
10.5. Caching, Paging and Refreshing
10.6. Referencing Another SQLContainer
10.7. Using FreeformQuery and FreeformStatementDelegate
10.8. Non-implemented methods of Vaadin container interfaces
10.9. Known Issues and Limitations
11. Advanced Web Application Topics
11.1. Handling Browser Windows
11.2. Embedding UIs in Web Pages
11.3. Debug Mode and Window
11.4. Request Handlers
11.5. Shortcut Keys
11.6. Printing
11.7. Google App Engine Integration
11.8. Common Security Issues
11.9. Navigating in an Application
11.10. Advanced Application Architectures
11.11. Managing URI Fragments
11.12. Drag and Drop
11.13. Logging
11.14. JavaScript Interaction
11.15. Accessing Session-Global Data
11.16. Server Push
12. Portal Integration
12.1. Overview
12.2. Creating a Portlet Project in Eclipse
12.3. Portlet UI
12.4. Deploying to a Portal
12.5. Installing Vaadin in Liferay
12.6. Handling Portlet Requests
12.7. Handling Portlet Mode Changes
12.8. Non-Vaadin Portlet Modes
12.9. Vaadin IPC for Liferay
III. Client-Side Framework
13. Client-Side Vaadin Development
13.1. Overview
13.2. Installing the Client-Side Development Environment
13.3. Client-Side Module Descriptor
13.4. Compiling a Client-Side Module
13.5. Creating a Custom Widget
13.6. Debugging Client-Side Code
14. Client-Side Applications
14.1. Overview
14.2. Client-Side Module Entry-Point
14.3. Compiling and Running a Client-Side Application
14.4. Loading a Client-Side Application
15. Client-Side Widgets
15.1. Overview
15.2. GWT Widgets
15.3. Vaadin Widgets
16. Integrating with the Server-Side
16.1. Overview
16.2. Starting It Simple With Eclipse
16.3. Creating a Server-Side Component
16.4. Integrating the Two Sides with a Connector
16.5. Shared State
16.6. RPC Calls Between Client- and Server-Side
16.7. Component and UI Extensions
16.8. Styling a Widget
16.9. Component Containers
16.10. Creating Add-ons
16.11. Migrating from Vaadin 6
16.12. Integrating JavaScript Components and Extensions
IV. Vaadin Add-ons
17. Using Vaadin Add-ons
17.1. Overview
17.2. Downloading Add-ons from Vaadin Directory
17.3. Installing Add-ons in Eclipse with Ivy
17.4. Using Add-ons in a Maven Project
17.5. Troubleshooting
18. Vaadin Charts
18.1. Overview
18.2. Installing Vaadin Charts
18.3. Basic Use
18.4. Chart Types
18.5. Chart Configuration
18.6. Chart Data
18.7. Advanced Uses
18.8. Timeline
19. Vaadin JPAContainer
19.1. Overview
19.2. Installing
19.3. Defining a Domain Model
19.4. Basic Use of JPAContainer
19.5. Entity Providers
19.6. Filtering JPAContainer
19.7. Querying with the Criteria API
19.8. Automatic Form Generation
19.9. Using JPAContainer with Hibernate
20. Mobile Applications with TouchKit
20.1. Overview
20.2. Considerations Regarding Mobile Browsing
20.3. Installing Vaadin TouchKit
20.4. Importing the Vornitologist Demo
20.5. Creating a New TouchKit Project
20.6. Elements of a TouchKit Application
20.7. Mobile User Interface Components
20.8. Advanced Mobile Features
20.9. Offline Mode
20.10. Building an Optimized Widget Set
20.11. Testing and Debugging on Mobile Devices
21. Vaadin TestBench
21.1. Overview
21.2. Installing Vaadin TestBench
21.3. Preparing an Application for Testing
21.4. Using Vaadin TestBench Recorder
21.5. Developing JUnit Tests
21.6. Taking and Comparing Screenshots
21.7. Running Tests in a Distributed Environment
21.8. Headless Testing
21.9. Known Issues
A. Songs of Vaadin