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

Screen Reader Support

As someone who is blind and uses a screen reader all the time, I quickly performed an accessibility test of the aria-placeholder attribute and checked its compatibility with screen readers. Here are my findings:

The placeholder provided with aria-placeholder is read by both NVDA and JAWS screen readers. However, when aria-placeholder is used in a custom text input, the value entered by the user is not exposed to the screen reader. The screen reader only announces the placeholder text and does not expose the entered value while navigating using Tab/Shift+Tab or using arrow keys within the custom text input element.

When aria-placeholder is used on a native HTML text input, the screen reader appropriately exposes the value, and all screen reader behaviors work as expected. Please note that according to the specification, we should not use the aria-placeholder attribute on native HTML text or text area elements.

The CodePen example used for this testing is under the heading “Working Example”.

This test was performed on April 30, 2024.

aria-placeholder Example

The aria-placeholder attribute needs to be used when constructing a custom control like a text input or text area. This placeholder should disappear when the user’s keyboard focus moves into the control or when data is entered into the element. Conversely, if there is no data in the control or when the user’s keyboard focus moves out of the element, the placeholder should reappear. Please note that the HTML placeholder attribute cannot be used for custom text or text area controls; instead, the placeholder attribute should be utilized within the HTML <input> or <textarea> elements exclusively.

Generally, using placeholders is not recommended due to the accessibility challenges they pose for various disability groups. Here is a note on the accessibility of placeholders, their impact, and examples.

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>

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>

Working Example

See the Pen aria-placeholder test by steve faulkner (@stevef) on CodePen.

Characteristics

Related Concepts

• HTML placeholder

Used in Roles

• textbox

Inherits into Roles

• searchbox

Value

• string
  • Unconstrained value type.

Semantic HTML

No HTML element equivalent. In HTML, there is a `placeholder` attribute that can be used with text inputs or textarea elements.

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

• WAI-ARIA 1.2 Specification
  Refer to the notes from the WAI-ARIA 1.2 specification for more information on aria-placeholder.
• A11Y Support
  The screenreader compatibility for each of the ARIA attributes is taken from the A11Y Support. Please refer to the original source if screenreader compatibility is updated for aria-placeholder.
• MDN Web Docs
  The browser compatibility for each of the ARIA attributes is taken from the MDN Web Docs. Please refer to the original source if browser compatibility is updated for aria-placeholder.