InputEvent — Schnittstelle · JavaScript-Referenz

Signatur

interface InputEvent extends UIEvent

Beschreibung

Die Schnittstelle InputEvent steht für Ereignisse, die Änderungen an bearbeitbaren Inhalten melden. Dazu gehören <input>- und <textarea>-Elemente sowie Elemente mit contenteditable. Die beiden wichtigsten Ereignistypen sind beforeinput (vor der Änderung, abbrechbar) und input (nach der Änderung, nicht abbrechbar).

Anders als Tastaturereignisse (keydown) erfasst InputEvent jede Art der Eingabe: Tippen, Einfügen, Ausschneiden, Drag & Drop, Autokorrektur, Spracheingabe, IME-Komposition (z. B. Chinesisch/Japanisch) und Rückgängig/Wiederholen. Deshalb ist es der richtige Weg, um auf Inhaltsänderungen zu reagieren.

Die wichtigsten Eigenschaften:

data – eingefügter Text als string oder null (z. B. beim Löschen).
inputType – Art der Änderung, z. B. "insertText", "deleteContentBackward", "insertFromPaste", "historyUndo", "formatBold".
dataTransfer – DataTransfer-Objekt bei Einfügen/Ablegen in contenteditable, sonst null.
isComposing – true, wenn das Ereignis während einer IME-Komposition auftritt.
getTargetRanges() – liefert ein Array von StaticRange-Objekten, die bei beforeinput den betroffenen Bereich beschreiben.

Eigene Instanzen lassen sich mit new InputEvent(type, options) erzeugen, etwa für Tests. Ein synthetisch ausgelöstes Ereignis ändert den Feldinhalt jedoch nicht – es informiert nur die Listener.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Name des Ereignisses, typischerweise `"input"` oder `"beforeinput"` (Konstruktor `new InputEvent()`).
$options	InputEventInit	{}	Optionales Objekt mit den `UIEventInit`-Feldern (`bubbles`, `cancelable`, `composed`, `view`, `detail`) sowie `data` (`string\|null`), `inputType` (`string`, Standard `""`), `isComposing` (`boolean`, Standard `false`), `dataTransfer` (`DataTransfer\|null`) und `targetRanges` (`StaticRange[]`).

Rückgabewert

Typ

InputEvent

Beschreibung

Der Konstruktor liefert ein neues InputEvent-Objekt. Im Browser erhält man Instanzen als Argument der Listener für input und beforeinput.

Beispiele

Live-Zeichenzähler mit input-Ereignis

const textarea = document.querySelector('#nachricht');
const zaehler = document.querySelector('#zaehler');
const MAX = 280;

textarea.addEventListener('input', (event) => {
  // event ist ein InputEvent
  console.log(event.inputType, JSON.stringify(event.data));
  zaehler.textContent = `${textarea.value.length} / ${MAX}`;
});

insertText "H" insertText "a" deleteContentBackward null insertFromPaste "Hallo Welt"

Nur Ziffern zulassen mit beforeinput

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

plz.addEventListener('beforeinput', (event) => {
  // Löschen, Rückgängig usw. immer erlauben
  if (!event.inputType.startsWith('insert')) return;

  // Während der IME-Komposition nicht eingreifen
  if (event.isComposing) return;

  if (event.data !== null && !/^\d+$/.test(event.data)) {
    event.preventDefault(); // Änderung wird verhindert
    console.log(`Abgelehnt: "${event.data}"`);
  }
});

Abgelehnt: "a"

Formatierung in contenteditable abfangen

const editor = document.querySelector('[contenteditable]');

editor.addEventListener('beforeinput', (event) => {
  // Strg+B / Strg+I usw. unterbinden – nur Klartext erlaubt
  if (event.inputType.startsWith('format')) {
    event.preventDefault();
    return;
  }

  if (event.inputType === 'insertFromPaste' && event.dataTransfer) {
    event.preventDefault();
    const text = event.dataTransfer.getData('text/plain');
    const [range] = event.getTargetRanges();
    console.log('Einfügen als Klartext:', text, range?.startOffset);
    document.execCommand('insertText', false, text);
  }
});

Einfügen als Klartext: Hallo 0

InputEvent synthetisch erzeugen (z. B. in Tests)

const feld = document.querySelector('#suche');

feld.addEventListener('input', (e) => {
  console.log(e instanceof InputEvent, e.inputType, e.data);
});

// Wert selbst setzen – dispatchEvent ändert den Inhalt nicht!
feld.value = 'js';
feld.dispatchEvent(new InputEvent('input', {
  bubbles: true,
  inputType: 'insertText',
  data: 'js'
}));

true insertText js

// Wichtig · Fallstricke

input ist nicht abbrechbar: preventDefault() wirkt nur bei beforeinput. Einige inputType-Werte (z. B. bestimmte IME-Kompositionsschritte wie insertCompositionText) lassen sich auch dort nicht verhindern.
Nicht jedes input-Ereignis ist ein InputEvent: Bei <select>, Checkboxen, Radiobuttons, type=\"range\" oder type=\"color\" liefern Browser teils ein einfaches Event ohne data/inputType. Vor Zugriff mit event instanceof InputEvent prüfen.
data ist nicht der Feldinhalt: Für den aktuellen Wert immer event.target.value (bzw. textContent) lesen. data ist bei Löschvorgängen null und bei <input>/<textarea> ist dataTransfer meist null – dort steht eingefügter Text in data.
IME beachten: Während der Komposition (isComposing === true) feuern viele Zwischenereignisse. Validierungen oder teure Operationen (Suche, API-Aufrufe) besser erst nach compositionend ausführen bzw. entprellen (debounce).
Programmatische Änderungen über element.value = … lösen kein input-Ereignis aus.
Kompatibilität: input mit data/inputType wird von allen modernen Browsern unterstützt; beforeinput und getTargetRanges() sind erst seit Firefox 87 (2021) überall verfügbar. Die Menge unterstützter inputType-Werte unterscheidet sich zwischen Browsern und Plattformen (vor allem mobil).
Sicherheit: Eingefügtes HTML aus dataTransfer.getData('text/html') niemals ungefiltert per innerHTML einsetzen (XSS-Gefahr) – vorher bereinigen oder als Klartext einfügen.

Siehe auch

FocusEvent PushEvent SnapEvent TextEvent UIEvent