KeyboardEvent.ctrlKey — Eigenschaft · JavaScript-Referenz

Signatur

KeyboardEvent.ctrlKey

Beschreibung

Die Eigenschaft ctrlKey gibt an, ob die Strg-Taste (Control) zu dem Zeitpunkt gedrückt war, an dem das KeyboardEvent ausgelöst wurde. Damit lassen sich Tastenkombinationen wie Strg+S (Speichern) oder Strg+Enter (Absenden) erkennen.

Typischerweise wertet man ctrlKey in einem keydown-Handler zusammen mit event.key oder event.code aus. Soll eine eigene Tastenkombination die Standardaktion des Browsers ersetzen, ruft man zusätzlich event.preventDefault() auf.

Wird die Strg-Taste selbst gedrückt, ist ctrlKey beim keydown bereits true (event.key === "Control"), beim zugehörigen keyup dagegen false. Die gleiche Eigenschaft gibt es auch bei MouseEvent, PointerEvent, WheelEvent und TouchEvent.

Rückgabewert

Typ

boolean

Beschreibung

true, wenn die Strg-Taste beim Auslösen des Ereignisses gedrückt war, sonst false.

Beispiele

Strg+S abfangen und eigene Speicherfunktion ausführen

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

document.addEventListener('keydown', (event) => {
  if (event.ctrlKey && event.key.toLowerCase() === 's') {
    event.preventDefault(); // Browser-Dialog "Seite speichern" unterdrücken
    save();
  }
});

Dokument gespeichert

Plattformübergreifend: Strg unter Windows/Linux, ⌘ unter macOS

const isMac = /Mac|iPhone|iPad/.test(navigator.platform);

const isShortcutModifier = (event) =>
  isMac ? event.metaKey : event.ctrlKey;

document.addEventListener('keydown', (event) => {
  if (isShortcutModifier(event) && event.key === 'k') {
    event.preventDefault();
    console.log('Suchpalette öffnen');
  }
});

Suchpalette öffnen

Strg+Enter sendet ein Formular aus einer Textarea ab

const textarea = document.querySelector('#nachricht');
const form = textarea.form;

textarea.addEventListener('keydown', (event) => {
  if (event.ctrlKey && event.key === 'Enter') {
    event.preventDefault();
    form.requestSubmit();
  }
});

Synthetisches Ereignis mit ctrlKey erzeugen (z. B. für Tests)

const evt = new KeyboardEvent('keydown', { key: 'z', ctrlKey: true });
console.log(evt.ctrlKey);

// Schreibgeschützt: Zuweisung hat keine Wirkung
evt.ctrlKey = false;
console.log(evt.ctrlKey);

true true

// Wichtig · Fallstricke

macOS: Die üblichen Tastenkürzel nutzen dort ⌘ (metaKey) statt Ctrl. Auf dem Mac löst Ctrl+Klick zudem ein Kontextmenü aus.
AltGr: Unter Windows wird AltGr als Strg+Alt gemeldet. Wer Zeichen wie @ oder € auf deutschen Tastaturen nicht versehentlich abfangen will, sollte event.getModifierState('AltGraph') prüfen oder altKey ausschließen.
Reservierte Kürzel: Manche Kombinationen (z. B. Strg+W, Strg+T, Strg+N) behält der Browser für sich. preventDefault() wirkt hier nicht.
Mit gedrückter Strg-Taste kann event.key je nach Tastaturbelegung abweichen. Wenn die physische Taste gemeint ist, ist event.code (z. B. "KeyS") oft verlässlicher.
Die Eigenschaft ist schreibgeschützt. Bei synthetischen Ereignissen setzt man sie über das Init-Objekt des Konstruktors new KeyboardEvent().
Wird in allen modernen Browsern unterstützt.

Siehe auch

KeyboardEvent.altKey KeyboardEvent.key KeyboardEvent.metaKey KeyboardEvent.code KeyboardEvent.shiftKey