Text Input

Description

A text input is a basic form control that allows users to enter and edit text. They are commonly used in forms for collecting information like names, email addresses, passwords, or search queries.

As such, a text input plays a role with other elements in helping users accomplish a task. A label associated with it informs users of the information that should be entered. A message might provide instructions or inform them when an entry is required. Its value is collected and submitted when its owning form is submitted. A feedback error message is usually presented when an entry fails a validation rule.

When to use

Use a text input to let a user enter free-form text, such as a name or address, in a form. (It is the most common form input on the web.) A text input may also be used in other applications where JavaScript is used to get its text value.

Native HTML text input

Examples

The following HTML form controls allow direct text entry:

• An HTML input element with no type attribute or type set to text, email, password, search, tel or url accepts a single line of text.

• An HTML textarea element accepts multiple lines of text.

Relevant attributes

An HTML input element can accept several attributes, depending on its type. The following are relevant for accessibility.

Attribute	Relevance
type	When set to anything other than text, an entry has specific semantics and, in most cases, an expected structure that should be conveyed to all users. Browsers may require a valid entry before accepting it. Users should be presented with an appropriate error message when making an invalid entry.
pattern	When set to a JavaScript regular expression (for example, [A-Za-z0-9]{3,16}) text input values that do not match prevent form submission. Users should be informed of the expected format and presented with an error message for an entry that doesn't match.
disabled	The disabled state should be conveyed to all users.
maxlength, minlength	Set to constrain the length of a valid entry. When set, the length constraint should be conveyed to all users.
placeholder	Providing a brief hint may be helpful when a particular format is expected. Do not use a placeholder as a label, as it will be removed when a user makes an entry.
required	Set when an entry is required for form submission. All users should be informed of the required state.
readonly	Set readonly when an input’s value may be set programmatically but not directly modified by a user. Users should be informed.

Custom text inputs

Replicating the native text input that works properly across a wide variety of applications presents significant challenges and is not recommended. Because the HTML specification limits elements that can be form controls to form-associated elements, creating a custom form control of any kind typically involves creating a web component as a form-associated custom element.

Nevertheless, by setting the contenteditable attribute on a generic HTML element and using JavaScript to handle users’ free-form text entry, a custom text input component can be constructed for use in a purpose-built custom web application. For usability, such a custom text input should match the interactive behavior and accessibility features of a native HTML text input.

Custom text input keyboard operation

A custom text input must be fully operable by keyboard alone, similar to a native <input type="text"> or <textarea>.

• Keyboard focus: An element with contenteditable set to ”true” or ”plaintext-only” is keyboard focusable in the tab sequence; unless it is nested inside another element with contenteditable set. In such a case, tabindex="0" may be set to place the nested content editable element in the keyboard focus order.

• Text entry and editing: With contenteditable set to ”true” or ”plaintext-only”, users can enter and edit text in a generic HTML element as they would in the native <textarea> element. When contenteditable is set to ”true”, users can also paste formatted text into the input.

• Single-line text input: By default, the Enter key creates a new line in a contenteditable element. To match the single-line <input type=”text”> behavior, a JavaScript event listener that captures Enter key events must be present. Note that, in any case, the Enter key will not perform a form submission when editing a contenteditable element.

Custom text input ARIA attributes

For custom text input components, ARIA attributes must be set to convey the element's role, state, and properties to assistive technologies that would otherwise be conveyed without them being set on native HTML inputs.

Note that setting ARIA elements has no effect on the element’s functionality and does not replace the need for JavaScript to handle a custom element’s behavior.

• Role: The component must have role="textbox" to identify it as a text input control.

• Accessible name: Set aria-labelledby to the id of a visible label or, with no visible label, set aria-label.

• Required: Set aria-required="true" to indicate that entry is required.

• Multiple lines: Set aria-multiline="true” to indicate that the input accepts line breaks, which mirrors the behavior of the standard HTML <textarea>. Note that an element with contenteditable=true is by default multiline.

• Validation: Set aria-invalid="true" when the input fails validation and associate an error message using aria-describedby to reference the id of the message..

Structure and semantics

All users must perceive and understand a text input in order to use it. They must know its purpose, when an entry is required, and receive helpful feedback when they have not made a valid entry.

As a base element, a text input has little structure but has many semantic properties. In most cases, native HTML elements convey their semantic information to assistive technologies without the addition of ARIA attributes. Where they do, adding redundant ARIA attributes could lead to inconsistencies and is not recommended. Otherwise, the appropriate ARIA attributes should be applied.

Semantic and structure accessibility tests

The Evinced component tests listed below check that both native and custom text inputs correctly present semantic information for assistive technologies.

Element has incorrect role

Field	Value
Impact	Critical
WCAG	4.1.2 Name, Role, Value
EN 301 549	9.4.1.2 Name, Role, Value
Section 508	1194.21(d)

Text input components must have an ARIA role of textbox or searchbox.

• A native HTML input element without a list attribute has the textbox role by default or when its type attribute is set to text, email, tel, or url.
• A native HTML textarea element has the textbox role.
• A native HTML input with type=password is considered as a secure or protected textbox by assistive technologies but has no explicit ARIA role. A custom text input should not be constructed for this purpose.
• A custom text input as described in the custom text inputs section must explicitly set role=textbox.

Missing contextual labelling

Field	Value
Impact	Critical
WCAG	1.3.1 Info and Relationships
EN 301 549	9.1.3.1 Info and Relationships
Section 508	N/A

Descriptive labels are necessary for users of assistive technology to understand the purpose of a form control. Without a programmatic association between a label and its input, screen reader users may not know what information is being requested.

• Ensure every text input has a clear, concise accessible name through a <label> element, aria-label, or aria-labelledby.

• Placeholder text must not be used as the visible label for a form control, as it disappears upon user input, negatively impacting accessibility and usability.

1<!-- standard HTML text input -->
2<label>
3    Enter your name *
4    <input type="text" required />
5    <span class="error-hint">Please fill in your name</span>
6</label>
7<!-- Custom text input -->
8<div
9    role="textbox"
10    aria-label="Address"
11    contenteditable
12    aria-required="true"
13></div>

Required field is missing required attribute

Field	Value
Impact	Serious
WCAG	1.3.1 Info and Relationships
EN 301 549	9.1.3.1 Info and Relationships
Section 508	N/A

HTML attributes that convey information about input constraints, such as a field being required, must be conveyed to assistive technologies. The required attribute is automatic for a native HTML input when present, but the aria-required="true" ARIA attribute must be explicitly set for all custom input elements that are visually indicated as required.

Ensure that:

• For native HTML input elements:

  • The native HTML input element has the required attribute.

  • Use the pseudo-selector :user-invalid to set a custom style to the invalid input error message.

• For custom text input elements:

  • When required, the element must have the aria-required="true" attribute.

1<!-- standard HTML text input -->
2<label>
3    Enter your name *
4    <input type="text" required />
5    <span class="error-hint">Please fill in your name</span>
6</label>
7<!-- Custom text input -->
8<div
9    role="textbox"
10    aria-label="Address"
11    contenteditable
12    aria-required="true"
13></div>

1/* Styles the input only after the user moves away or submits */
2input:user-invalid {
3    border: 2px solid darkred;
4    background-color: #fff0f0;
5}
6/* Optional: Add a custom message icon or text using a sibling selector */
7.error-hint {
8    display: none;
9}
10
11input:user-invalid + .error-hint {
12    display: block;
13    color: red;
14}

Asterisk fields not marked as required

Field	Value
Impact	Serious
WCAG	1.3.1 Info and Relationships
EN 301 549	9.1.3.1 Info and Relationships
Section 508	N/A

It is a common design pattern to add an asterisk suffix to the label of the input element to mark it as required. This method cannot replace the use of the required/aria-required attributes, as it will not trigger accessible notifications to assistive technology users to mark which input fields were left unaddressed.

Textarea not fully supported

When a text input is intended to accept multiple lines of text, it must be identifiable as such to assistive technologies. The HTML <textarea> element does that without the addition of any ARIA attributes. For custom components, the aria-multiline="true" attribute must be applied to the element with role="textbox".

Keyboard users expect the Enter key to submit a form and might be reluctant to use it to enter a new line in a multiline text field, where it should not. Applying the Enter key in an HTML textarea element will create a line break rather than a form submission, and a custom multiline text input (role="textbox") should do likewise. Setting aria-multiline="true" on a custom text input informs screen reader users to expect the same behavior as the native textarea.

Evinced’s component tester does not currently test multiline text inputs for input validation or accessible error notification.

Non-semantic input has type

Field	Value
Impact	Minor
WCAG	N/A
EN 301 549	N/A
Section 508	N/A

The type attribute (e.g., type="email", type="password") is a specific feature of the native HTML <input> element. Applying a type attribute to a non-semantic element (like a <div> or <span>) has no effect on browser behavior or validation. For custom text inputs, use appropriate ARIA roles and attributes (like role="textbox") and manage validation logic manually via JavaScript.

Conflicting disabled values

Field	Value
Impact	Serious
WCAG	4.1.2 Name, Role, Value
EN 301 549	9.4.1.2 Name, Role, Value
Section 508	1194.21(d)

Ensure that the visual state of a text input matches its programmatic state. A common error occurs when an element is visually styled as disabled but lacks the disabled attribute if it’s a native input or aria-disabled="true" if it is a custom input. Conversely, avoid situations where an input is programmatically disabled but still appears interactive, as this confuses users with low vision and those navigating via keyboard.

Avoid setting both disabled and aria-disabled="true" as it can create a confusing experience for assistive technology users.

Relationships

A text input is a form control that plays a role with other elements to achieve a user’s objective. By far its most common application is in a form where its entered value is collected and submitted along with other form inputs when the form is submitted. The relationships between all of the components of the application needs to be clear to users so that they can successfully achieve their objective in using it. A text input can have several relationships with other elements:

• A text input should be labeled by visible text in a <label> element if it is a native HTML input or a generic <span> or <div> element referenced by an aria-labelledby attribute on a native or custom text input.

• A text input with associated helper text, description or error message informs assistive technologies of that relationship by setting aria-describedby to the id of the element containing the message. For an error, the nature of that relationship is conveyed by also setting aria-invalid on the input.

• When a text input is used in a form it is “owned” by the form and its (valid) entry is included with the form’s data when it is submitted. When possible, a text input should be contained within the form’s DOM hierarchy and that implicit relationship can be conveyed to assistive technology users. Otherwise, set aria-owns on the form element with the id of the text input.

Relationship accessibility tests

Missing accessible error notification

Field	Value
Impact	Critical
WCAG	3.3.1 Error Identification
EN 301 549	9.3.3.1 Error Identification
Section 508	N/A

When a user submits invalid data in a text input field, the resulting error must be clearly and accessibly announced to all users, including those using assistive technologies (AT) like screen readers. Simply displaying red text or an icon is insufficient for accessibility.

Key Requirements for Developers:

1. Announce the Error Message: The error message text must be programmatically linked to the input field using the aria-describedby attribute on the input. The value of aria-describedby must be the ID of the element containing the error message. This ensures screen readers read the error when the input is focused.

Example HTML:

1<label for="email">Email Address</label>
2<input
3    type="email"
4    id="email"
5    aria-invalid="true"
6    aria-describedby="email-error"
7/>
8<div id="email-error" style="color: red;">
9    Please enter a valid email address.
10</div>

2. Mark the Element as Invalid: Set the aria-invalid attribute to "true" on the input element when the data is invalid. This informs AT users that the input requires correction. Remove this attribute or set it to "false" once the input is valid.

3. Ensure Immediate Announcement (Live Region): To guarantee that the error message is announced immediately upon validation failure (e.g., after the user submits a form or tabs out of the field), the container holding the error message should be part of a live region. This is typically done by placing the error summary or the individual error messages within an element with aria-live="polite".

   Good Practice: If the error message is displayed away from the input field (e.g., a form-wide error summary), make the error summary a live region.

1<div role="alert" aria-live="polite">
2    Form submission failed. Please review the errors below.
3</div>

4. Manage Focus (Recommended): After a validation failure, the focus should ideally be set to:
   • The first input field with an error, OR
   • A form-wide error summary link that jumps the user to the first error.
5. This practice brings the user's attention directly to the problem area, and because of aria-describedby, the error message will be read out as the input receives focus.

Summary of Implementation Steps (for a single input):

State	Input Attribute	Error Message Container	Notes
Initial/Valid	No aria-invalid or aria-invalid="false"	Hidden/empty
Invalid	aria-invalid="true"	Visible	The error message element must have an ID that matches the input's aria-describedby value.

In summary, to achieve accessible error notification, developers must:

• Use aria-invalid="true" on the failing input.
• Link the error message text to the input using aria-describedby.
• Ensure the error message is announced immediately, preferably by making the containing region an aria-live region, and/or by setting focus to the problematic input.

Could not infer error trigger

This error occurs when the test runner cannot programmatically detect how or when the component validates user input. For a text input to be accessible, it must signal its invalid state (via aria-invalid) and provide a description (via aria-describedby) when validation fails.

To resolve this, ensure the component correctly implements ARIA validation states. If your component uses specific input patterns (e.g., a specific date format or character limit), the component tester requires a sample of "bad data" to trigger the validation logic. Provide an invalid string to the invalidValueExample option in your test configuration. This allows the runner to simulate a user error and verify that the accessibility tree correctly updates to notify assistive technology users of the failure.

No accessible error notification

Field	Value
Impact	Serious
WCAG	3.3.1 Error Identification
EN 301 549	9.3.3.1 Error Identification
Section 508	N/A

When an empty value is submitted on a required field, a visible and programmatic error notification must be shown. Screen reader users will not receive an indication that the form submission failed or why it failed, as they are not alerted to the missing required value.

Ensure that there is a visible message describing the error (e.g., "This field is required") and programmatically point to it from the input field using the aria-describedby attribute.

Aria-invalid value did not change

Field	Value
Impact	Moderate
WCAG	4.1.2 Name, Role, Value
EN 301 549	9.4.1.2 Name, Role, Value
Section 508	1194.21(d)

The aria-invalid attribute must dynamically update based on the current state of the input. If an error is corrected, aria-invalid must be set to false or removed entirely. If the attribute remains true after the user has fixed the error, assistive technologies will continue to report the field as invalid, preventing the user from confidently proceeding with form submission.

Avoid aria-errormessage

Field	Value
Impact	Serious
WCAG	4.1.2 Name, Role, Value
EN 301 549	9.4.1.2 Name, Role, Value
Section 508	1194.21(d)

Although aria-errormessage is part of the ARIA specification, browser and screen reader support for it is currently inconsistent. To ensure maximum compatibility across all assistive technologies, it is recommended to use aria-describedby to link the input to its error message. aria-describedby is more robustly supported and ensures the error text is read when the user focuses on the invalid field.

Nested interactive elements

Field	Value
Impact	Serious
WCAG	4.1.2 Name, Role, Value
EN 301 549	9.4.1.2 Name, Role, Value
Section 508	1194.21(d)

Avoid nesting interactive elements (like buttons, links, or other inputs) inside a text input or its custom container.

Why this is a problem:

• Screen Reader Navigation Issues: Screen readers may fail to navigate to the nested child elements. Instead, the screen reader might treat the entire block (the parent text input and all nested elements) as a single focusable entity. Additionally the screen reader is likely to ignore the semantics of the nested interactive element, preventing screen reader users from operating it.
• Keyboard Inaccessibility: The internal, nested controls become unreachable or unusable for keyboard-only users because the focus never properly lands on the nested interactive elements. This effectively traps the user's focus on the parent element.

Avoid aria-owns

While aria-owns can define a parent-child relationship between elements that are not nested in the DOM, it is often poorly supported by assistive technologies and can lead to a confusing reading order. For text inputs, it is best practice to use standard DOM hierarchy and include inputs within the form that owns it.

or aria-describedby and aria-controls to establish relationships between the input and its supplementary elements (like dropdown suggestions or helper text).

Operation

All users should be able to enter and edit text in a text input field.

Pointer operation

A user with a mouse, touch screen, or other pointing device should be able to:

1. Activate the input: Click or tap on the text input field to place the focus and display a cursor (or blinking insertion point).

2. Input text: After activation, the user can type text using an on-screen or physical keyboard.

3. Edit text: The user can move the cursor within the text field by clicking or tapping at a new position, select text by dragging the pointer, and then delete, overwrite, or paste content.

4. Clear/Delete: If a clear button or similar control is present, the user can click/tap it to empty the field.

Keyboard operation

A user operating with a keyboard should be able to:

1. Focus: Use the Tab key to navigate to and place focus on the text input field.

2. Input text: Once focused, typing text will insert characters at the cursor position.

3. Navigate text:

   • Left Arrow / Right Arrow to move the cursor one character at a time.

   • Ctrl + Left Arrow / Ctrl + Right Arrow (Windows/Linux) or Option + Left Arrow / Option + Right Arrow (macOS) to move the cursor one word at a time.

   • Home / End to move the cursor to the beginning/end of the text.

4. Select text:

   • Shift + Arrow keys to select characters.

   • Shift + Ctrl + Arrow keys (Windows/Linux) or Shift + Option + Arrow keys (macOS) to select words.

   • Ctrl + A or Cmd + A to select all text.

5. Edit text:

   • Backspace to delete the character before the cursor.

   • Delete to delete the character after the cursor or the selected text.

   • Standard editing commands: Ctrl/Cmd + C (Copy), Ctrl/Cmd + X (Cut), Ctrl/Cmd + V (Paste).

6. Submit/Exit: The Enter key may submit an associated form, depending on context, but typically does not act within a single-line text input itself unless configured specifically. The Tab key moves focus to the next interactive element.

Operability tests

Keyboard accessible

Field	Value
Impact	Critical
WCAG	2.1.1 Keyboard, 2.4.3 Focus Order
EN 301 549	9.2.1.1 Keyboard, 9.2.4.3 Focus Order
Section 508	N/A

A text input must be focusable unless it is disabled. This requirement is crucial for keyboard users who rely on the ability to navigate the element.

Standard HTML input elements inherently possess focusability when not disabled. For non-semantic text inputs, focusability can be conferred by incorporating the tabindex="0" attribute onto the input element, or by using the contenteditable attribute, which additionally manages the keyboard functionality for text entry.

1<div role="textbox" aria-label="Address" contenteditable></div>

Deprecated keypress listener

The keypress event is deprecated and behaves inconsistently across different browsers and input methods (like IME for international languages). For custom text inputs, developers should use keydown or input events. Using keydown ensures that functional keys (like Backspace and Arrows) are captured, while the input event is the most reliable way to detect when the value of the textbox has changed.