HTMLElement.tabIndex — Eigenschaft · JavaScript-Referenz

Signatur

HTMLElement.tabIndex

Beschreibung

Die Eigenschaft tabIndex ist mit dem HTML-Attribut tabindex verknüpft. Sie legt fest, ob ein Element per Tastatur (Tab-Taste) fokussierbar ist und an welcher Stelle es in der Tab-Reihenfolge steht. Beim Setzen wird das Attribut aktualisiert, beim Lesen erhält man immer eine ganze Zahl.

Die Werte haben folgende Bedeutung:

0: Das Element ist fokussierbar und wird in der natürlichen Dokumentreihenfolge angesprungen. Das ist der empfohlene Wert, um eigene Bedienelemente (z. B. ein <div> als Button) tastaturbedienbar zu machen.
-1 (oder ein anderer negativer Wert): Das Element ist per Skript mit focus() fokussierbar, wird aber beim Tabben übersprungen. Typisch für Dialoge, Überschriften als Sprungziele oder „Roving Tabindex“ in Widgets.
Positive Werte: Das Element wird vor allen Elementen mit 0 angesprungen, aufsteigend sortiert. Davon wird aus Gründen der Barrierefreiheit dringend abgeraten.

Ohne gesetztes Attribut liefert die Eigenschaft für von Natur aus fokussierbare Elemente (<a href>, <button>, <input>, <select>, <textarea> …) den Wert 0, für alle anderen -1.

Parameter

Name	Typ	Default	Beschreibung
$value	number	0 bzw. -1 (abhängig vom Element)	Beim Setzen: ganze Zahl. Nicht-ganzzahlige Werte werden in einen `long` umgewandelt (Nachkommastellen abgeschnitten, `NaN` wird zu `0`).

Rückgabewert

Typ

number

Beschreibung

Die aktuelle Tab-Position als ganze Zahl. 0 = in natürlicher Reihenfolge fokussierbar, negativ = nur per Skript fokussierbar, positiv = bevorzugte Reihenfolge.

Beispiele

Standardwerte auslesen

const button = document.createElement('button');
const div = document.createElement('div');
const link = document.createElement('a');

console.log(button.tabIndex); // natürlich fokussierbar
console.log(div.tabIndex);    // nicht fokussierbar
console.log(link.tabIndex);   // ohne href nicht fokussierbar
link.href = '/start';
console.log(link.tabIndex);

0 -1 -1 0

Eigenes div-Bedienelement tastaturbedienbar machen

const toggle = document.querySelector('.custom-toggle');

toggle.tabIndex = 0; // in die Tab-Reihenfolge aufnehmen
toggle.setAttribute('role', 'button');

const activate = () => toggle.classList.toggle('active');
toggle.addEventListener('click', activate);
toggle.addEventListener('keydown', (event) => {
  if (event.key === 'Enter' || event.key === ' ') {
    event.preventDefault();
    activate();
  }
});

console.log(toggle.getAttribute('tabindex'));

Fehlermeldung per Skript fokussieren (tabIndex = -1)

const showError = (message) => {
  const box = document.querySelector('#error-box');
  box.textContent = message;
  box.tabIndex = -1; // fokussierbar, aber nicht per Tab erreichbar
  box.focus();
  console.log(document.activeElement === box);
};

showError('Bitte füllen Sie alle Pflichtfelder aus.');

true

Roving Tabindex in einer Werkzeugleiste

const items = [...document.querySelectorAll('[role="toolbar"] button')];
let current = 0;

// Nur ein Element ist per Tab erreichbar
items.forEach((btn, i) => { btn.tabIndex = i === current ? 0 : -1; });

document.querySelector('[role="toolbar"]').addEventListener('keydown', (e) => {
  if (e.key !== 'ArrowRight' && e.key !== 'ArrowLeft') return;
  items[current].tabIndex = -1;
  current = (current + (e.key === 'ArrowRight' ? 1 : -1) + items.length) % items.length;
  items[current].tabIndex = 0;
  items[current].focus();
});

// Wichtig · Fallstricke

Keine positiven Werte verwenden: Sie brechen die natürliche Reihenfolge, verwirren Tastatur- und Screenreader-Nutzer und sind schwer wartbar. Besser die DOM-Reihenfolge anpassen.
Fokussierbar heißt nicht bedienbar: Ein <div tabindex=\"0\"> reagiert nicht automatisch auf Enter/Leertaste und hat keine Rolle. Wo möglich, native Elemente wie <button> nutzen.
Attribut entfernen: Um zum Standardverhalten zurückzukehren, element.removeAttribute('tabindex') verwenden – tabIndex = null setzt den Wert auf 0.
Deaktivierte Elemente (disabled), versteckte Elemente (display: none, hidden) sowie Inhalte in inert-Bereichen sind trotz tabIndex nicht fokussierbar.
Die Eigenschaft ist in allen Browsern unterstützt; SVGElement.tabIndex existiert analog. Ältere Safari-Versionen fokussieren Links per Tab erst nach Aktivierung einer Systemeinstellung.

Siehe auch

HTMLOptionElement.index HTMLElement.hidden HTMLElement.title HTMLElement.dataset HTMLElement.inert