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
Related ARIA techniques
N/A
Compatibility
TBD: Add support information for common UA and AT product combinations