WAI-ARIA: aria-placeholder (Property)
Description
New in ARIA 1.1
Defines a short hint (a word or short phrase) intended to aid the user with data entry when the control has no value. A hint could be a sample value or a brief description of the expected format.
Authors SHOULD NOT use aria-placeholder instead of a label as their purposes are different: The label indicates what kind of information is expected. The placeholder text is a hint about the expected value. See related aria-labelledby and aria-label.
Authors SHOULD present this hint to the user by displaying the hint text at any time the control’s value is the empty string. This includes cases where the control first receives focus, and when users remove a previously-entered value.
Note: As is the case with the related HTML placeholder attribute, use of placeholder text as a replacement for a displayed label can reduce the accessibility and usability of the control for a range of users including older users and users with cognitive, mobility, fine motor skill or vision impairments. While the hint given by the control’s label is shown at all times, the short hint given in the placeholder attribute is only shown before the user enters a value. Furthermore, placeholder text may be mistaken for a pre-filled value, and as commonly implemented the default color of the placeholder text provides insufficient contrast and the lack of a separate visible label reduces the size of the hit region available for setting focus on the control.
Browser Compatibility For aria-placeholder
| desktop | mobile | |||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|
ariaPlaceholder | ChromeFull support81 | EdgeFull support81 | FirefoxNo supportNo | Internet ExplorerNo supportNo | OperaFull support68 | SafariFull support12.1 | WebView AndroidFull support81 | Chrome AndroidFull support81 | Firefox for AndroidNo supportNo | Opera AndroidFull support58 | Safari on iOSFull support12.2 | Samsung InternetFull support13.0 |
Screen Reader Support For aria-placeholder
| Expectation | JAWS | Narrator | NVDA | Orca | TalkBack | VoiceOver (iOS) | VoiceOver (macOS) | ||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| Chrome | Edge | Firefox | Edge | Chrome | Edge | Firefox | Firefox | Chrome | Safari | Safari | |
| MUST convey aria-placeholder for text field with no value | supported | supported | supported | supported | supported | supported | supported | unknown | supported | supported | supported |
| MUST NOT convey aria-placeholder when (HTML attribute) placeholder is defined | supported | supported | none | supported | supported | supported | supported | unknown | supported | supported | supported |
| SHOULD contribute to the accessible name | supported | supported | supported | supported | supported | supported | supported | unknown | supported | supported | supported |
| MAY convey aria-placeholder for text field with value | none | none | none | supported | none | none | none | unknown | supported | none | none |
aria-placeholder Example
HTML Example
The following example shows a searchbox in which the user has entered a value:
<span id="label">Birthday:</span>
<div contenteditable role="searchbox" aria-labelledby="label" aria-placeholder="MM-DD-YYYY">03-14-1879</div>HTML Example 2
The following example shows the same searchbox in which the user has not yet entered a value or has removed a previously-entered value:
<span id="label">Birthday:</span>
<div contenteditable role="searchbox" aria-labelledby="label" aria-placeholder="MM-DD-YYYY">MM-DD-YYYY</div>Characteristics
Related Concepts
- HTML placeholder
Used in Roles
Inherits into Roles
Value
- string
- Unconstrained value type.
Semantic HTML
No HTML element equivalent.
The aria-placeholder attribute is meant to simulate the HTML5 behavior of the placeholder attribute and make it valid within other simulated control types and roles where the HTML5 placeholder attribute is not valid.
All scripting, styling, and functionality of the use of this attribute must be implemented manually by the developer since the attribute itself is not meant to have any effect on browser functionality.
The aria-placeholder attribute and the HTML5 placeholder attribute should not be used together on the same element, nor should aria-placeholder be used on native form controls where the HTML5 placeholder attribute is appropriate.
Reference
- W3C (opens new window)
- A11Y Support
- MDN Web Docs
