Using the textbox role

Description

This technique demonstrates how to use the textbox role and describes the effect it has on browsers and assistive technology.

The textbox role is used to identify an element that allows the input of free-form text. When this role is added to an element, the browser will send out an accessible textbox event to assistive technology products which can then notify the user about it.

The default is for single line input where ENTER or RETURN would submit the form, e.g. as with HTML <input type=”text”>. Where this is multi-line and the input of line breaks is supported, e.g. when using a HTML <textarea>, it is necessary to also set aria-multiline=”true”.

Where a text field has been made read-only this should be indicated by setting aria-readonly=”true” on the element.

Possible effects on user agents and assistive technology 

When the textbox role is added to an element, or such an element becomes visible, the user agent should do the following:

• Expose the element as having a textbox role in the operating system's accessibility API.
• Fire an accessible textbox event using the operating system's accessibility API if it supports it.

Assistive technology products should listen for such an event and notify the user accordingly:

• Screen readers should announce its label and role when focus first lands on a textbox. If it also contains content, this should be announced as with a regular textbox.
• Screen magnifiers may enlarge the textbox.

Examples

Example 1: Adding the role in the HTML code for single line input

The snippet below shows how the textbox role is added directly into the html source code. 

<input type="text" role="textbox" value="Here is some text" />

Example 2: Adding the role in the HTML code for multi-line input

The snippet below shows how the textbox role is added directly into the html source code. 

<textarea role="textbox" aria-multiline="true">Here is some text</textarea>

Working Examples:

Notes 

• Authors should be aware of the distinction between single line and multi-line text input when designing a field.
• Read-only fields should be indicated via aria-readonly.

ARIA attributes used

• textbox

Related ARIA techniques 

N/A

Compatibility

TBD: Add support information for common UA and AT product combinations

Additional resources