Element: keydown — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("keydown", handler)

Beschreibung

Das keydown-Event wird beim Herunterdrücken einer Taste ausgelöst, und zwar auf dem Element, das gerade den Fokus hat. Ist kein Element fokussiert, geht es an document.body. Es blubbert (bubbles) bis zu document und window hoch und lässt sich abbrechen. Der Handler bekommt ein KeyboardEvent. Registrieren kannst du ihn mit addEventListener("keydown", handler) oder über die Eigenschaft onkeydown.

Anders als das veraltete keypress kommt keydown bei allen Tasten, also auch bei Modifikatortasten (Shift, Ctrl, Alt, Meta), Pfeiltasten, Escape und Funktionstasten. Deshalb eignet es sich für Tastenkürzel, Spielsteuerung, Tastaturnavigation in eigenen Widgets (z. B. Listen oder Menüs) und zum Abfangen bestimmter Eingaben.

Die wichtigsten Eigenschaften des Events:

event.key: der erzeugte Wert unter Berücksichtigung des Tastaturlayouts, z. B. "a", "A", "Enter", "ArrowUp"
event.code: die physische Taste unabhängig vom Layout, z. B. "KeyA", "Space"
event.ctrlKey, shiftKey, altKey, metaKey: welche Modifikatoren gedrückt sind
event.repeat: true, wenn das Event durch automatische Tastenwiederholung ausgelöst wurde
event.isComposing: true während einer IME-Eingabe (z. B. Japanisch oder Chinesisch)

Mit event.preventDefault() verhinderst du die Standardaktion. Je nach Taste ist das das Einfügen eines Zeichens, das Scrollen mit Pfeiltasten oder die Leertaste oder ein Browser-Kürzel wie Ctrl+S. Für Aktionen beim Loslassen der Taste gibt es keyup.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Event-Name: `"keydown"`.
$handler Pflicht	(event: KeyboardEvent) => void		Callback, das bei jedem Tastendruck ein `KeyboardEvent` erhält.
$options	boolean \| AddEventListenerOptions	false	Optional, z. B. `{ capture: true }`, `{ once: true }` oder `{ signal }`, um den Listener über einen `AbortController` zu entfernen.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Rückgabewert des Handlers wird ignoriert. Um die Standardaktion abzubrechen, rufe event.preventDefault() auf.

Beispiele

Tastenkürzel Strg/Cmd+S abfangen

const save = () => console.log('Dokument gespeichert');

document.addEventListener('keydown', (event) => {
  const mod = event.ctrlKey || event.metaKey; // Windows/Linux bzw. macOS
  if (mod && event.key.toLowerCase() === 's') {
    event.preventDefault(); // Speichern-Dialog des Browsers unterdrücken
    if (!event.repeat) save();
  }
});

Dokument gespeichert

Modal mit Escape schließen und Listener wieder entfernen

const modal = document.querySelector('#modal');

const onKeydown = (event) => {
  if (event.key === 'Escape') {
    modal.hidden = true;
    document.removeEventListener('keydown', onKeydown);
    console.log('Modal geschlossen');
  }
};

const openModal = () => {
  modal.hidden = false;
  document.addEventListener('keydown', onKeydown);
};

openModal();

Modal geschlossen (nach Druck auf Escape)

Pfeiltasten-Navigation in einer Liste per onkeydown

const list = document.querySelector('#menu'); // <ul tabindex="0"> mit <li>-Einträgen
const items = [...list.querySelectorAll('li')];
let index = 0;

const highlight = () => items.forEach((li, i) => li.classList.toggle('active', i === index));

list.onkeydown = (event) => {
  if (event.key === 'ArrowDown') index = Math.min(index + 1, items.length - 1);
  else if (event.key === 'ArrowUp') index = Math.max(index - 1, 0);
  else if (event.key === 'Enter') return console.log('Gewählt:', items[index].textContent);
  else return;
  event.preventDefault(); // Scrollen der Seite verhindern
  highlight();
};

highlight();

Gewählt: Einstellungen

Spielsteuerung über physische Tasten (code) mit AbortController

const pressed = new Set();
const controller = new AbortController();

window.addEventListener('keydown', (e) => {
  if (['KeyW', 'KeyA', 'KeyS', 'KeyD'].includes(e.code)) pressed.add(e.code);
}, { signal: controller.signal });

window.addEventListener('keyup', (e) => pressed.delete(e.code), { signal: controller.signal });

// Später: alle Listener auf einmal entfernen
// controller.abort();

// Wichtig · Fallstricke

Nur fokussierte Elemente empfangen keydown. Ein <div> braucht dafür tabindex="0". Globale Kürzel registrierst du auf document oder window.
key oder code? Für Zeichen und Kürzel nimmst du key, weil es das Layout berücksichtigt. Für positionsbasierte Steuerung wie WASD nimmst du code, denn auf einer AZERTY-Tastatur liegt „W“ auf "KeyZ". keyCode und which sind veraltet.
Tastenwiederholung: Wird eine Taste gehalten, feuert keydown mehrfach. Prüfe event.repeat, wenn eine Aktion nur einmal passieren soll.
IME-Eingabe: Während der Komposition ist event.isComposing true, und key kann den Wert "Process" haben (keyCode 229). Solche Events solltest du bei Enter-Kürzeln ignorieren.
Reservierte Kürzel wie Ctrl+W, Ctrl+T oder Alt+Tab lassen sich mit preventDefault() nicht zuverlässig abfangen.
Barrierefreiheit: Überschreibe keine Standardtasten wie Tab oder Screenreader-Kürzel, ohne eine Alternative anzubieten.
Für Texteingaben ist oft das input-Event besser geeignet. keydown erfasst weder Einfügen per Maus noch Autovervollständigung oder Spracheingabe.
Browser-Kompatibilität: keydown, key und code werden von allen modernen Browsern unterstützt.

Siehe auch

KeyboardEvent KeyboardEvent.key KeyboardEvent.code EventTarget.addEventListener() Event.preventDefault()