ARIA property
aria-placeholder
A hint shown in an empty field. It is not a label and does not replace one.
It carries the same short hint an HTML placeholder would, for a field the host language cannot give one to. It is a hint about the format rather than a name for the field.
Which roles may carry aria-placeholder
- Value
- string
- Filed as
- A property, which is how ARIA files it and not a rule about how often it changes.
- Roles that may carry it
textbox- Roles that inherit it
searchbox
Those lists are not advice. Browsers are required to ignore a non-global attribute sitting on a role that does not support it, so aria-placeholder on the wrong element is not weak, it is absent. You can read it in the DOM and nobody using a screen reader can.
Every role above comes from the specification's own list for this attribute, checked name for name. The normative definition stays with the W3C, in the aria-placeholder section of the ARIA specification.
Keeping aria-placeholder true
The spec says twice not to use this instead of a label, and the reason is what happens as soon as somebody types. The hint goes, and with it the only clue about what the field wanted, which the spec notes lands hardest on older users and on people with cognitive, mobility, fine motor or vision disabilities. So the obligation here is really a design one. Give the field a real name that stays put and keep this for the format example. A field whose only name is its placeholder still has an accessible name, which means it passes an automated name check and fails the person filling it in.
How aria-placeholder gets checked
There are test rules that check an ARIA attribute is one that exists, is allowed on the role underneath it, and carries a value of the right type. What they map to is ARIA's own author requirements rather than any WCAG criterion, so a misplaced attribute breaks ARIA without being a WCAG failure by itself. It becomes one under 4.1.2 Name, Role, Value the moment the missing or wrong value means the control's state cannot be worked out programmatically, which is what usually happens next.
Nothing automated catches the failure this page is about. A stale value is a valid value, on a permitted role, with the right type. It is only wrong about the world.
Attributes you will meet alongside aria-placeholder
- aria-activedescendant Points at the item inside a composite widget that is currently active, when focus stays on the container.
- aria-autocomplete How a text field predicts what you are typing.
- aria-errormessage Points at the message explaining why this field is invalid. Only meaningful while aria-invalid is set.
- aria-haspopup Says this control opens something, and what kind of thing it opens. A menu, a dialog, a listbox.
- aria-invalid Says a field's value has failed validation.
- aria-multiline Whether a text field takes more than one line, which changes what Enter does.
- aria-readonly The value can be read but not changed. Unlike disabled, it is still part of the form.
- aria-required Says a field has to be filled in before the form can be submitted.
Every ARIA state and property · Every ARIA role · ARIA explained