Element.ariaPosInSet — Eigenschaft · JavaScript-Referenz

Signatur

Element.ariaPosInSet

Beschreibung

Die Eigenschaft ariaPosInSet gehört zu den ARIA-Reflexions-Eigenschaften (ARIAMixin) der Element-Schnittstelle. Sie liest und schreibt direkt das HTML-Attribut aria-posinset. Damit teilst du assistiven Technologien wie Screenreadern mit, an welcher Stelle ein Element innerhalb einer Gruppe steht, etwa „Eintrag 5 von 120“.

Gebraucht wird das vor allem dann, wenn nicht alle Elemente einer Gruppe im DOM vorhanden sind. Typische Fälle sind virtualisierte Listen, unendliches Scrollen, seitenweise geladene Suchergebnisse oder teilweise ausgeklappte Bäume (role="treeitem"). Sind alle Elemente im DOM, berechnet der Browser die Position selbst. Das Attribut ist dann unnötig.

Der Wert ist immer ein String mit einer ganzen Zahl ab 1, auch wenn er eine Zahl darstellt. Fast immer setzt du zusätzlich ariaSetSize (aria-setsize), damit die Gesamtgröße der Gruppe bekannt ist. Erlaubt ist das Attribut nur bei bestimmten Rollen: listitem, option, treeitem, menuitem, menuitemradio, menuitemcheckbox, radio, tab, row (in Baumtabellen), article und comment.

Parameter

Name	Typ	Default	Beschreibung
$value	string \| null	null	Beim Setzen: Die Position als String mit einer ganzen Zahl ab `1`, z. B. `"3"`. Mit `null` wird das Attribut `aria-posinset` entfernt.

Rückgabewert

Typ

string | null

Beschreibung

Der aktuelle Wert des Attributs aria-posinset als String. Ist das Attribut nicht gesetzt, ist der Wert null.

Beispiele

Wert lesen und ändern

// HTML: <li id="item" role="option" aria-posinset="4" aria-setsize="16">Birne</li>
const item = document.getElementById('item');

console.log(item.ariaPosInSet);        // "4"
console.log(typeof item.ariaPosInSet); // "string"

item.ariaPosInSet = '5';
console.log(item.getAttribute('aria-posinset')); // "5"

4 string 5

Virtualisierte Liste: Position und Gesamtzahl setzen

// Von 10.000 Datensätzen werden nur die sichtbaren Einträge gerendert
const TOTAL = 10000;
const list = document.querySelector('[role="listbox"]');

const renderWindow = (startIndex, rows) => {
  list.replaceChildren();
  rows.forEach((text, i) => {
    const option = document.createElement('div');
    option.role = 'option';
    option.textContent = text;
    option.ariaPosInSet = String(startIndex + i + 1); // Position beginnt bei 1
    option.ariaSetSize = String(TOTAL);
    list.append(option);
  });
};

renderWindow(200, ['Eintrag 201', 'Eintrag 202', 'Eintrag 203']);
console.log(list.firstElementChild.ariaPosInSet);

201

Attribut entfernen und Unterstützung prüfen

const el = document.querySelector('[role="treeitem"]');

if ('ariaPosInSet' in Element.prototype) {
  el.ariaPosInSet = null; // entfernt aria-posinset
} else {
  el.removeAttribute('aria-posinset'); // Fallback für ältere Browser
}

console.log(el.hasAttribute('aria-posinset'));

false

// Wichtig · Fallstricke

Der Wert ist ein String: el.ariaPosInSet + 1 ergibt \"41\" statt 5. Zum Rechnen mit Number() umwandeln.
Die Zählung beginnt bei 1, nicht bei 0. Beim Umrechnen von Array-Indizes + 1 nicht vergessen.
Der Wert sollte nie größer als aria-setsize sein. Setze beide Attribute gemeinsam und bei allen Elementen der Gruppe einheitlich.
Nur bei passenden Rollen verwenden. Bei anderen Rollen wird das Attribut von assistiven Technologien ignoriert.
Sind alle Elemente der Gruppe im DOM, das Attribut besser weglassen. Falsche Angaben verwirren Screenreader-Nutzer mehr als fehlende.
Browser-Kompatibilität: Firefox unterstützt die Reflexions-Eigenschaft erst ab Version 119. Für ältere Browser setAttribute('aria-posinset', …) verwenden. Das Attribut selbst wird überall unterstützt.

Siehe auch

Element.ariaSetSize Element.ariaLevel Element.role Element.ariaSelected Element.setAttribute() Element.getAttribute() Element.ariaOrientation