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 a single line input where Enter or Return would submit the form — usually an HTML <input> with type="text". Where the field is multi-line and the input of line breaks is supported, as in an 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.

Note: Opinions may differ on how assistive technology should handle this technique. The information provided above is one of those opinions and therefore not normative.

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.

<div role="textbox" contenteditable="true"></div>

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.

<div role="textbox" contenteditable="true" aria-multiline="true"></div>

Notes

Authors should be aware of the distinction between single line and multi-line text input when designing a field.
Authors should avoid using this role in <input type="text"> or <textarea> elements. See Notes on Using ARIA in HTML.
Authors should use contenteditable="true" in the elements using this role.
Read-only fields should be indicated via aria-readonly.

ARIA attributes used

Related ARIA techniques

N/A