Single-line textbox [_] …

A single-line textbox is a form feature that enables readers to enter a single line of text on the webpage. Single-line textboxes are used in order forms for example.

Use a multi-line textbox, if your readers need more space for their text input.

How to

Write [_] at the start of a line to get a simple single-line textbox. That is a left square bracket, an underscore and a right square bracket. Optionally add a space followed by text after the right square bracket to label the textbox like in the first two examples below.

You can optionally add a colon followed by a placeholder text of your choice after the underscore inside the square brackets [_:placeholder]. The placeholder text is displayed when the textbox is otherwise empty.

An exclamation mark immediately after the right square bracket [_]! makes the textbox require input for a successful form submission. Use this for strictly necessary information such as the email field in an email newsletter subscription form.

You can add an arrow [_]-> composed of a hyphen and a greater-than sign followed by a filename immediately after the right square bracket or exclamation mark. This loads input suggestions from the given file. The suggestions file must not contain tabs. If the file contains only one line, that line is used as default text for the textbox. If the file contains multiple lines, each line except the first line is understood as an input suggestion.

Input suggestions that match what a reader has already typed into the textbox are usually shown as a drop-down list from which readers can select a suggestion. A single-line textbox with input suggestions is also called combobox, since it combines the functionality of a textbox and a selection widget.

There can be multiple consecutive textboxes in one block, each placed at the start of a new line. The first textbox can be preceded by a question, task or topic to summarize what the textboxes are for.

Examples

The first example shows a textbox that uses the placeholder feature to display the expected format of user input. Mind that the placeholder text is not visible anymore once a user starts to type. Consider to describe the expected format in the text after the textbox, if you want readers to be able to still read it after they have started typing.

[_:YYYY-MM-DD] date of birth

The second example consists of a task followed by two text boxes. The first textbox must be filled out for a successful submission.

Please enter your contact details:
[_]! email
[_] phone

The third example, which asks for the reader’s favorite dog breed, uses a suggestions file containing hundreds of breed names. You can download the file here. While the reader types into the box, matching suggestions are offered and can be selected. But readers can also enter content such as Labradoodle or Mutt that is not among the suggestions.

What’s your favorite dog breed?
[_]->/stuff/breeds.txt

For developers

When Aneamal is translated to HTML, a single-line textbox will be turned into an input element. Its type is text. A placeholder attribute contains the placeholder text, if available. The input is followed by a label element that contains the text that labels the textbox, if available. Each textbox, together with its label, is wrapped in a HTML span element. The block that contains the textboxes is wrapped in a HTML fieldset element. So the first example becomes:

<fieldset>
<span><input id='_1' name='_1' form='_f1' type='text' placeholder='YYYY-MM-DD'> <label for='_1'>date of birth</label></span>
</fieldset>

If a textbox is marked as required, the corresponding HTML input element gets an attribute required. Multiple textboxes are separated by br elements. The optional task, topic or question that precedes the first textbox in a block is wrapped in an HTML legend element inside the fieldset. The second example becomes:

<fieldset>
<legend>Please enter your contact details:</legend>
<span><input id='_2' name='_1' form='_f2' type='text' required> <label for='_2'>email</label></span><br>
<span><input id='_3' name='_2' form='_f2' type='text'> <label for='_3'>phone</label></span>
</fieldset>

By the way, you can change the labels’ position with CSS. The following stylesheet puts the labels above their textbox for example:

fieldset > span {
	display: inline-flex;
	flex-direction: column-reverse;
}

HTML input elements corresponding to single-line textboxes with a suggestions file either have a value or a list attribute. If the suggestions file contains only one line, that line goes into the value attribute.

The list attribute is used in case of a suggestions file with multiple lines. The attribute contains an automatically generated ID that is the same as in the id attribute of a subsequent HTML datalist element. That datalist element contains an option element for each suggestion from the suggestions file. The suggestion is stored in the HTML option element’s value attribute.

So the third example becomes:

<fieldset>
<legend>What’s your favorite dog breed?</legend>
<span><input id='_4' name='_1' form='_f3' type='text' list='_5'></span>
<datalist id='_5'>
<option value='Affenpinscher'>
<option value='Afghan Hound'>
<option value='Airedale Terrier'>
<option value='Akita'>
…
</datalist>
</fieldset>