• Atom
  • CORE COMPONENT
  • Taxonomic name: A-TEXTBOX
  • Added on: v4.0.0 (20/07/18)
  • Updated on: v2023.01 (26/05/23)

Textbox

The text box control allows users to add a single line of text as a response to a form question.

Design and usage

  • For use with the following input types:

    • Email
    • Number
    • Password
    • Search
    • Telephone
    • Text
    • URL
  • Text fields with a standard character length (eg. dates, telephone numbers, post codes etc) should be appropriately restricted; the length of the field should be appropriate to the information being asked for.
  • Please also see International contact if wanting to capture international dialing codes with a telephone number.
  • Field labels should be displayed outside of the input field.
  • Ensure text area fields have a correctly associated label; this not only provides context to each field for assistive technology users, but also a larger clickable area to select the field.
  • Clicking / pressing on a label for a text area field should cause the input to gain focus.
  • Users should be allowed to copy and paste if necessary.
  • See style guide for detailed colour and typography rules.
  • For date input, it may be prefereable to use a single auto-formatting textbox; see Memorable date textbox page for further details
  • Aria-invalid must be used to indicate when an error has occurred with this element
  • Aria-describedby must be used to link any help, instructional and/or error text with the element/form fields
  • Do not use inappropriate restrictions, eg. password fields or email addresses may require longer line lengths.

Examples

Standard textbox

Interactive example

Code example

<div class="m-form-row">
	<label class="a-label" for="...">...</label>
	<div class="m-form-row__content">
		<input type="..." id="..." name="..." class="a-textbox [ Modifier ]" />
	</div>
</div>

Valid textbox

Interactive example

Code example

<div class="m-form-row is-valid">
	<label class="a-label" for="...">...</label>
	<div class="m-form-row__content">
		<p class="m-form-row__validation-message">...</p>
		<input type="..." id="..." name="..." class="a-textbox [ Modifier ]" />
	</div>
</div>

Errored textbox

Interactive example

Code example

<div class="m-form-row is-error">
	<label class="a-label" for="...">...</label>
	<div class="m-form-row__content">
		<p class="m-form-row__error-message" id="..."><span class="u-hidden--visually">Error: </span>...</p>
		<input type="..." id="..." name="..." class="a-textbox [ Modifier ]" aria-invalid="true" aria-describedby="..." />
	</div>
</div>

Disabled textbox

Interactive example

Code example

<div class="m-form-row is-disabled">
	<label class="a-label" for="...">...</label>
	<div class="m-form-row__content">
		<input type="..." id="..." name="..." class="a-textbox [ Modifier ]" disabled />
	</div>
</div>

Restricted length fields (1 - 11)

Password textbox

Interactive example

Code example

<div class="m-form-row">
	<label class="a-label" for="...">...</label>
	<div class="m-form-row__content">
		<input type="password" id="..." name="..." placeholder="..." class="a-textbox a-textbox--password [ Modifier ]" data-module="a-textbox-password" />
	</div>
</div>

Required textbox

<div class="m-form-row">
	<label class="a-label" for="...">...</label>
	<div class="m-form-row__content">
		<input type="..." id="..." name="..." class="a-textbox [ Modifier ]" aria-required="true" />
	</div>
</div>

Development and test

Notes for developers

Field labels should be displayed outside of the input not inside.

Line-breaks are automatically removed from the input value.

Use the maxlength attribute to specify the maximum length of the value that can be entered.

Some browsers include the functionality to be able to show the value of any password entered into a password field. Do not attempt to either recreate this functionality or turn it off.

When disabling form elements, do not solely rely on the is-disabled class, but ensure that the disabled attribute is also set on the relevant form element or input. If an entire set of form elements is to be disabled, the is-disabled class and disabled attribute should be added directly to the fieldset instead, and not to each individual element within it. However if only one element from the set is disabled, then the class and attribute should be applied to that element only.

If the native form validation needs to be disabled set the novalidate attribute on the form.

Input types

Care should be taken when choosing input field types for various uses, particularly with regard to number entry, as making the wrong selection could prevent users from inputting the required details into a form. For further information, see the form introduction page.

Aria usage for errors and help text

To aid screen reader users in completing forms without error and also with understanding and fixing any errors that have occured, some additional aria attributes are now recommended to be applied across all form fields/rows.

All form row help, explanatory text, form row instructions and form row errors must have a unique id assigned to them and be appropriately linked to either the individual form input or the form row using aria-describedby. This ensures that the help text is read out immediately on focus of the form input/fieldset. When there is more that one item that requires referencing within the aria-describedby attribute the id values must be supplied in the form of a space separated list. For example if there is an error with id of 'err1' and help text with id of 'help1' the value for the aria-describedby attribute would be 'err1 help1'.

All inline form error messages should start with the hidden text 'Error: ' so that when read by out by a screen reader it is immediately clear that the text being read is an error message.

All erroring form fields (or fieldset if a group or radios/checkboxes) must have aria-invalid="true" set on them, ensuring that when a user focus' on an errored form field, the field will be announced as invalid, so the user is then aware that there in an issue that requires fixing.

When linking help or errors, or even adding aria-invalid to the markup careful consideration must be taken as to where it is most appropriate to apply the value. The following rules should be used to decide where the attribute(s) should be applied.

  • Single form field - All attributes should be applied directly to that form field
  • Group of form fields but only one in error or help text applies to only one - Apply the attribute(s) to the only field in error or where the help text applies
  • Group of form field where all in error or the help text applies to all - Apply the attribute(s) to the groups surrounding fieldset (form row)

There may situations where more than one of these rules applies to the overall form row for example a date range where the instruction text applies to both fields so should be linked to the fieldset for the date range but one of the two fields is in error so the error should be linked to just that field not to the fieldset.

Important messages

To help those using assistive technologies, make sure that success/error messages which need to be announced to users have their aria attributes updated to role="alert" and/or aria-live="assertive".

Using autocomplete

Users appreciate when websites save them time by automatically filling common fields like names, email addresses and other frequently used fields, plus it helps to reduce potential input errors, especially on virtual keyboards and small devices.

Browsers use many methods to determine which fields they can auto-populate based on previously specified data by the user, and you can give hints to the browser by providing both the name attribute and the autocomplete attribute on each input element.

Further details can be found in the developer notes on the form introduction page.

Ensure that the autocomplete attribute is set for off for any field that may have privacy concerns eg. passwords, card/account numbers etc.

Notes for testers

  • Not all the input types are understood by all browsers so they fall back to being a standard text input. This means that they may allow the entry of invalid characters, any invalid entries should be highlighted when the form is submitted like any other errors.
  • Ensure that all form fields have a correctly associated label. This not only provides context to each field for assistive technology users but also a larger clickable area to select the field. Clicking/pressing on a label for a single input field should cause the input to gain focus.
  • Ensure that autofill is not available for sensitive fields such as password, card/account number etc.
  • Users should be able to copy and paste if necessary.
  • If the field has been restricted in length the maximum number of characters allowed must also be restricted. Note: many browsers will not do this for number field and older browser will not do this at all.

Classes overview

The following table gives you a quick overview of the CSS classes that can be applied.

Class Outcome Required Applied to Comments
.a-textbox Styling for the text input Yes input  
.a-textbox--1-character Modifier for restricting the textbox length for 1 character   .a-textbox maxlength must be set to 1
.a-textbox--2-character Modifier for restricting the textbox length for 2 characters   .a-textbox maxlength must be set to 2
.a-textbox--3-character Modifier for restricting the textbox length for 3 characters   .a-textbox maxlength must be set to 3
.a-textbox--4-character Modifier for restricting the textbox length for 4 characters   .a-textbox maxlength must be set to 4
.a-textbox--5-character Modifier for restricting the textbox length for 5 characters   .a-textbox maxlength must be set to 5
.a-textbox--6-character Modifier for restricting the textbox length for 6 characters   .a-textbox maxlength must be set to 6
.a-textbox--7-character Modifier for restricting the textbox length for 7 characters   .a-textbox maxlength must be set to 7
.a-textbox--8-character Modifier for restricting the textbox length for 8 characters   .a-textbox maxlength must be set to 8
.a-textbox--9-character Modifier for restricting the textbox length for 9 characters   .a-textbox maxlength must be set to 9
.a-textbox--10-character Modifier for restricting the textbox length for 10 characters   .a-textbox maxlength must be set to 10
.a-textbox--11-character Modifier for restricting the textbox length for 11 characters   .a-textbox maxlength must be set to 11
.a-textbox--password Modifier for adding the textbox some more padding-right   .a-textbox  

Keyboard operations

TAB

Tabbing to an input field should make the input clearly visually different so that the focus point on the page is obvious to the user.

Component releases

  • Added on: v4.0.0 (20/07/18)
  • Updated on: v2023.01 (26/05/23)

Latest update:

  • updated: Add password textbox modifier.

Full version history

A full history of changes and enhancements detailing all minor and major updates to the component.

View full version history

Want something new in Framework, or to chat about an issue you're having with it?

Contact the team