--- title: TextField order: 9 layout: page --- [[components.textfield]] = [classname]#TextField# ifdef::web[] [.sampler] image:{live-demo-image}[alt="Live Demo", link="http://demo.vaadin.com/sampler/#ui/data-input/text-input/text-field"] endif::web[] ((("[classname]#TextField#", id="term.components.textfield", range="startofrange"))) [classname]#TextField# is one of the most commonly used user interface components. It is a [classname]#Field# component that allows entering textual values with keyboard. The following example creates a simple text field: [source, java] ---- // Create a text field TextField tf = new TextField("A Field"); // Put some initial content in it tf.setValue("Stuff in the field"); ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.basic[on-line example, window="_blank"]. The result is shown in <>. [[figure.components.textfield.basic]] .[classname]#TextField# Example image::img/textfield-example.png[width=40%, scaledwidth=50%] Value changes are handled by adding a listener using [methodname]#addValueChangeListener()# method, as in most other fields. The value can be acquired with [methodname]#getValue()# directly from the text field or from the parameter passed to the event listener. [source, java] ---- // Handle changes in the value tf.addValueChangeListener(event -> // Do something with the value Notification.show("Value is: " + event.getValue())); ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.inputhandling[on-line example, window="_blank"]. [classname]#TextField# edits [classname]#String# values, but you can use [classname]#Binder# to bind it to any property type that has a proper converter, as described in <>. Much of the API of [classname]#TextField# is defined in [classname]#AbstractTextField#, which allows different kinds of text input fields, which do not share all the features of the single-line text fields. [[figure.components.textfield.api]] .Text field class relationships image::img/textfield-diagram-hi.png[width=80%, scaledwidth=100%] [[components.textfield.length]] == String Length The [methodname]#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 [classname]#AbstractTextField# level. Notice that the maximum length setting does not affect the width of the field. You can set the width with [methodname]#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, but the __em__ width is not exactly the width of a letter and varies by browser and operating system. There is no standard way in HTML for setting the width exactly to a number of letters (in a monospaced font). [[components.textfield.textchangeevents]] == Configuring the Granularity of Value Change Events ((("[classname]#Text change events#", id="term.components.textfield.textchangeevents", range="startofrange"))) Often you want to control how frequently [classname]#TextField# value changes are transmitted to the server. Sometimes the changes should be sent only after the field loses focus. In the other extreme, it can sometimes be useful to receive events every time the user presses a key. The __value 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. ((([classname]#TextChangeEventMode#))) You can set the text change event mode of a [classname]#TextField# with [methodname]#setTextChangeEventMode()#. The allowed modes are defined in [classname]#TextChangeEventMode# enum and are as follows: [parameter]#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 [methodname]#setInputEventTimeout()#. As with the [parameter]#TIMEOUT# mode, a text change event is forced before a possible [classname]#ValueChangeEvent#, even if the user did not keep a pause while entering the text. + This is the default mode. [parameter]#TextChangeEventMode.TIMEOUT#:: 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 [methodname]#setInputEventTimeout()#. + If a [classname]#ValueChangeEvent# would occur before the timeout period, a [classname]#TextChangeEvent# is triggered before it, on the condition that the text content has changed since the previous [classname]#TextChangeEvent#. [parameter]#TextChangeEventMode.EAGER#:: 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. [source, java] ---- // Text field with maximum length TextField tf = new TextField("My Eventful Field"); tf.setValue("Initial content"); tf.setMaxLength(20); // Counter for input length Label counter = new Label(); counter.setValue(tf.getValue().length() + " of " + tf.getMaxLength()); // Display the current length interactively in the counter tf.addValueChangeListener(event -> { int len = event.getValue().length(); counter.setValue(len + " of " + tf.getMaxLength()); }); tf.setValueChangeMode(ValueChangeMode.onKeyPress()); ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.textchangeevents.counter[on-line example, window="_blank"]. The result is shown in <>. [[figure.components.textfield.textchangeevents]] .Text Change Events image::img/textfield-textchangeevents.png[width=35%, scaledwidth=50%] (((range="endofrange", startref="term.components.textfield.textchangeevents"))) [[components.textfield.css]] == CSS Style Rules [source, css] ---- .v-textfield { } ---- The HTML structure of [classname]#TextField# is extremely simple, consisting only of an element with the [literal]#++v-textfield++# style. For example, the following custom style uses dashed border: [source, css] ---- .v-textfield-dashing { border: thin dashed; background: white; /* Has shading image by default */ } ---- See the http://demo.vaadin.com/book-examples-vaadin7/book#component.textfield.css[on-line example, window="_blank"]. The result is shown in <>. [[figure.components.textfield.css]] .Styling TextField with CSS image::img/textfield-css.png[] The style name for [classname]#TextField# is also used in several components that contain a text input field, even if the text input is not an actual [classname]#TextField#. This ensures that the style of different text input boxes is similar. (((range="endofrange", startref="term.components.textfield")))