Element.ariaAutoComplete — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaAutoComplete

Beschreibung

Die Eigenschaft ariaAutoComplete gehört zum ARIAMixin und steht deshalb auf jedem Element zur Verfügung. Sie spiegelt das Attribut aria-autocomplete direkt wider: Wer die Eigenschaft liest, bekommt den Attributwert, und wer sie setzt, ändert das Attribut. Einen Umweg über getAttribute() oder setAttribute() braucht es nicht.

Mit aria-autocomplete teilen Sie Hilfstechnologien wie Screenreadern mit, ob ein Eingabefeld beim Tippen Vorschläge macht und wie diese erscheinen. Das ist vor allem bei selbst gebauten Kombinationsfeldern (role="combobox"), Suchfeldern und Textfeldern mit Vorschlagsliste wichtig. Erlaubt sind diese Werte:

"none": Es gibt keine Vorschläge (Standard).
"inline": Der vorgeschlagene Rest des Wortes erscheint markiert direkt im Feld hinter dem Cursor.
"list": Die Vorschläge erscheinen in einem separaten Popup, etwa einer listbox.
"both": Es gibt eine Vorschlagsliste und zusätzlich eine Inline-Vervollständigung.

Die Eigenschaft beschreibt nur das Verhalten. Die Vervollständigung selbst müssen Sie als Entwickler programmieren. Bei "list" oder "both" gehören normalerweise auch aria-controls, aria-expanded und aria-activedescendant dazu.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null		Beim Setzen: einer der Werte `"none"`, `"inline"`, `"list"` oder `"both"`. Mit `null` wird das Attribut `aria-autocomplete` entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-autocomplete. Ist das Attribut nicht gesetzt, kommt null zurück (nicht "none").

Beispiele

Wert auslesen und ändern

// HTML: <input id="suche" type="text" role="combobox" aria-autocomplete="inline">
const feld = document.getElementById('suche');

console.log(feld.ariaAutoComplete);

// Auf Vorschlagsliste umstellen
feld.ariaAutoComplete = 'list';
console.log(feld.getAttribute('aria-autocomplete'));

inline list

Barrierefreies Kombinationsfeld per JavaScript aufbauen

const input = document.createElement('input');
input.type = 'text';
input.id = 'stadt';
input.setAttribute('role', 'combobox');
input.ariaAutoComplete = 'list';
input.ariaExpanded = 'false';
input.setAttribute('aria-controls', 'stadt-liste');

const liste = document.createElement('ul');
liste.id = 'stadt-liste';
liste.setAttribute('role', 'listbox');
liste.hidden = true;

const staedte = ['Berlin', 'Bremen', 'Bonn', 'Hamburg', 'München'];

input.addEventListener('input', () => {
  const q = input.value.toLowerCase();
  const treffer = q ? staedte.filter((s) => s.toLowerCase().startsWith(q)) : [];
  liste.replaceChildren(...treffer.map((s, i) => {
    const li = document.createElement('li');
    li.setAttribute('role', 'option');
    li.id = `stadt-opt-${i}`;
    li.textContent = s;
    return li;
  }));
  liste.hidden = treffer.length === 0;
  input.ariaExpanded = String(treffer.length > 0);
});

document.body.append(input, liste);
console.log(input.ariaAutoComplete, input.ariaExpanded);

list false

Fehlendes Attribut erkennen und entfernen

const el = document.createElement('div');
console.log(el.ariaAutoComplete); // Attribut fehlt

el.ariaAutoComplete = 'both';
console.log(el.outerHTML);

el.ariaAutoComplete = null; // entfernt das Attribut
console.log(el.hasAttribute('aria-autocomplete'));

// Effektiven Wert mit Rückfall auf den Standard ermitteln
const effektiv = el.ariaAutoComplete ?? 'none';
console.log(effektiv);

null <div aria-autocomplete="both"></div> false none

// Wichtig · Fallstricke

Keine Prüfung der Werte: Der Browser nimmt jeden String an, z. B. el.ariaAutoComplete = 'ja'. Hilfstechnologien werten ungültige Werte dann meist als "none". Prüfen Sie die Werte deshalb selbst.
null statt "none": Fehlt das Attribut, liefert die Eigenschaft null. Für den Standardwert ?? verwenden (siehe Beispiel 3).
Nicht verwechseln mit autocomplete: Das HTML-Attribut autocomplete (bzw. input.autocomplete) steuert das Autofill des Browsers. aria-autocomplete beschreibt nur für Hilfstechnologien, wie sich Ihre eigene Vervollständigung verhält.
Nur wenn es wirklich zutrifft: Setzen Sie den Wert nur, wenn tatsächlich Vorschläge angeboten werden. Falsche Angaben verwirren Screenreader-Nutzer.
Kompatibilität: Chromium und Safari unterstützen ARIA-Reflection seit Längerem, Firefox erst ab Version 119. Für ältere Browser setAttribute('aria-autocomplete', …) verwenden, das funktioniert überall.

Siehe auch

Element.role ElementInternals.ariaMultiSelectable Element.ariaAtomic Element.ariaColCount Element.ariaMultiLine