Text input box
[This documentation is preliminary and is subject to change.]
.png "A sample of what a standard text input box control looks like")
Control description
A text input box lets the user enter and edit a text or numeric value via the physical or on-screen keyboard. Using text wrapping, a text input box can be configured to accept a single line or multiple lines of text.
Usage guidance
Use a text input box to let the user enter a text value, or to edit a value already entered. If the input needs to be constrained, that's possible, too. You can limit the number of characters that can be entered, and you can choose from a list of input scopes, which limit the input to a particular character set or format—for example, a number, a Uniform Resource Identifier (URI), or a currency.
Factors that indicate against using a list box include:
- The value being entered is approximate, and/or relative to another quantity on the same page. Consider a slider control.
- Only a fairly small set of values are valid, for example, the days of the week. Consider a drop-down list, or a list box, especially if the values are more than a few characters long.
- The value entered is likely to be adjusted after the result is observed—for example, volume or brightness is being set. Consider a slider control.
- Special meanings are assigned to particular values entered into the text input box. Consider a drop-down list, a list box, a checkbox or radio buttons.
Appearance and interaction
A text input box is composed of a rectangular border with an editable text area within it. On a touch-enabled device, the on-screen keyboard appears when the text input box receives focus.
Design guidelines
- If it’s not obvious what the user should type into a text input box, or if there are any constraints on input, then set a label, or placeholder text. A label is visible whether or not the text input box has a value. Placeholder text is displayed inside the text input box and disappears once a value has been entered.
- Consider giving the control a width that’s appropriate for the range of values that can be entered. Bear in mind that word length can vary between languages, so take localization into account.
- A text input box is typically single-line (text wrapping off). When users need to enter or edit a long string, set the text input box to multi-line (text wrapping on).
- Generally, you use a text input box for editable text. But you can make a text input box read-only so that its content can be read, selected, and copied, but not edited.
- If you need to reduce clutter in a view, consider making a set of text input boxes appear only when a controlling checkbox is checked. You can also bind the enabled state of a text input box to a control such as a checkbox.
- A common use for a text input box is to accept a search term or filter. Consider having the app respond to each keystroke instead of waiting for the value to be committed. That way, you can implement search suggestions or a dynamic filter while the user types.
- Consider how you want a text input box to behave when it contains a value and the user taps it. The default behavior is appropriate for editing the value rather than replacing it—the insertion point is placed between words and nothing is selected. If replacing is the most common use case for a given text input box, you can select all the text in the field whenever the control receives focus; typing replaces the selection.
- If you want to limit the input to a particular character set or format—for example, a number, a URI, or a currency—set the input scope appropriately. This determines which on-screen keyboard is used.
Examples
.png "A screenshot that illustrates the standard text input box control")