Signatur
Beschreibung
Die Eigenschaft ariaPlaceholder gehört zur ARIA-Reflexion der Element-Schnittstelle. Sie spiegelt das Attribut aria-placeholder wider: Beim Lesen erhalten Sie dessen aktuellen Wert als Zeichenkette, beim Schreiben wird das Attribut gesetzt oder geändert. Sie müssen also nicht mehr getAttribute() bzw. setAttribute() verwenden.
aria-placeholder ist ein kurzer Hinweis, etwa ein Beispielwert oder eine Formatangabe, der Screenreadern mitteilt, was in ein leeres Eingabefeld gehört. Das Attribut ist nur für selbst gebaute Eingabe-Widgets gedacht, zum Beispiel ein <div contenteditable> mit role="textbox" oder role="searchbox". Bei nativen <input>- und <textarea>-Elementen nehmen Sie stattdessen das HTML-Attribut placeholder.
Wichtig: aria-placeholder ändert nichts an der Darstellung. Den sichtbaren Platzhaltertext müssen Sie selbst anzeigen, etwa per CSS mit :empty::before, und ausblenden, sobald der Benutzer etwas eingibt. Ein Platzhalter ersetzt außerdem keine Beschriftung. Dafür gibt es aria-label oder aria-labelledby.
Parameter
| Name | Typ | Default | Beschreibung |
|---|---|---|---|
| $value | string | null | null | Beim Setzen: der neue Hinweistext. Mit null wird das Attribut aria-placeholder entfernt. |
Rückgabewert
aria-placeholder oder null, wenn das Attribut nicht gesetzt ist.Beispiele
Wert auslesen
// HTML: <div id="txt" role="textbox" contenteditable="true" aria-placeholder="5102"></div>
const box = document.getElementById('txt');
console.log(box.ariaPlaceholder);Hinweis setzen und entfernen
const box = document.querySelector('[role="textbox"]');
box.ariaPlaceholder = 'z. B. 12345';
console.log(box.getAttribute('aria-placeholder'));
// Attribut vollständig entfernen
box.ariaPlaceholder = null;
console.log(box.hasAttribute('aria-placeholder'));Eigenes Such-Widget mit sichtbarem Platzhalter
// CSS: [data-empty]::before { content: attr(aria-placeholder); color: #888; }
const search = document.createElement('div');
search.setAttribute('role', 'searchbox');
search.contentEditable = 'true';
search.ariaLabel = 'Artikel suchen';
search.ariaPlaceholder = 'Suchbegriff eingeben …';
search.dataset.empty = '';
// Sichtbaren Platzhalter nur bei leerem Feld anzeigen
search.addEventListener('input', () => {
search.toggleAttribute('data-empty', search.textContent.trim() === '');
});
document.body.append(search);
console.log(search.ariaPlaceholder);// Wichtig · Fallstricke
- Browserunterstützung: Firefox unterstützt die ARIA-Reflexion erst ab Version 119. In älteren Browsern liefert die Eigenschaft
undefined, und Zuweisungen setzen kein Attribut. Als Rückfall verwenden SiesetAttribute('aria-placeholder', …). - Nicht zusammen mit nativen Formularelementen verwenden. Bei
<input>und<textarea>ist das HTML-Attributplaceholderrichtig. Beide gleichzeitig zu setzen kann dazu führen, dass Screenreader den Hinweis zweimal vorlesen. - Das Attribut ist nur bei den Rollen
textboxundsearchboxzulässig. Bei anderen Rollen wird es ignoriert. - Ein Platzhalter ist keine Beschriftung. Er verschwindet bei der Eingabe und wird von manchen Hilfstechnologien nicht vorgelesen. Geben Sie daher immer zusätzlich eine zugängliche Beschriftung an.
- Den sichtbaren Text müssen Sie selbst darstellen. Achten Sie dabei auf ausreichenden Farbkontrast (WCAG).