Element: compositionupdate — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("compositionupdate", handler)

Beschreibung

Das Ereignis compositionupdate gehört zu den Kompositionsereignissen (CompositionEvent). Es wird ausgelöst, wenn ein Eingabemethoden-Editor (IME) oder ein anderes Textkompositionssystem den noch nicht bestätigten Kompositionstext ändert, etwa wenn der Nutzer beim japanischen Tippen weitere Silben eingibt oder einen anderen Kandidaten auswählt. Die Reihenfolge lautet: compositionstart → beliebig viele compositionupdate → compositionend.

Über die Eigenschaft event.data erhält man den aktuellen Kompositionstext (also die komplette vorläufige Zeichenkette, nicht nur das zuletzt hinzugekommene Zeichen). Das Ereignis ist nützlich, um während der Eingabe eine Vorschau anzuzeigen, Zeichenzähler live zu aktualisieren oder eigene Editoren (z. B. auf contenteditable-Basis) IME-fähig zu machen.

Registrieren lässt sich der Handler per addEventListener("compositionupdate", handler) oder über die Eigenschaft oncompositionupdate, wobei letztere nicht in allen Browsern als IDL-Attribut existiert – addEventListener ist daher der empfohlene Weg. Das Ereignis blubbert (bubbles: true), ist aber nicht abbrechbar.

Typischer Anwendungsfall: Such- oder Validierungslogik, die auf input reagiert, sollte während einer laufenden Komposition pausieren und erst nach compositionend mit dem endgültigen Text arbeiten, da Zwischenstände für den Nutzer noch keine Bedeutung haben.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"compositionupdate"`.
$handler Pflicht	(event: CompositionEvent) => void		Callback, der ein `CompositionEvent` erhält. Wichtig: `event.data` (aktueller Kompositionstext) und `event.locale` (veraltet).
$options	boolean \| AddEventListenerOptions	false	Optionen wie `{ once, passive, capture, signal }` oder ein Boolean für die Capture-Phase.

Rückgabewert

Typ

void

Beschreibung

addEventListener gibt nichts zurück. Der Handler erhält ein CompositionEvent-Objekt.

Beispiele

Kompositionstext live protokollieren

const input = document.querySelector('#name');

input.addEventListener('compositionstart', () => console.log('Start'));
input.addEventListener('compositionupdate', (event) => {
  // event.data enthält den kompletten vorläufigen Text
  console.log('Update:', event.data);
});
input.addEventListener('compositionend', (event) => {
  console.log('Ende:', event.data);
});

Start Update: に Update: にほ Update: にほん Update: 日本 Ende: 日本

Vorschau-Anzeige und Suche erst nach Abschluss

const search = document.querySelector('#search');
const preview = document.querySelector('#preview');
let composing = false;

search.addEventListener('compositionstart', () => { composing = true; });
search.addEventListener('compositionupdate', (e) => {
  preview.textContent = `Eingabe läuft: ${e.data}`;
});
search.addEventListener('compositionend', () => {
  composing = false;
  preview.textContent = '';
  runSearch(search.value);
});
search.addEventListener('input', (e) => {
  // Während der Komposition keine Suche starten
  if (composing || e.isComposing) return;
  runSearch(search.value);
});

function runSearch(term) {
  console.log('Suche nach:', term);
}

Suche nach: 東京

Über die on-Property und wieder entfernen

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

// Variante 1: on-Property (nicht überall als Attribut verfügbar)
editor.oncompositionupdate = (e) => console.log('on-Property:', e.data);

// Variante 2: addEventListener mit AbortController
const controller = new AbortController();
editor.addEventListener('compositionupdate', (e) => {
  console.log('Listener:', e.data, e.type);
}, { signal: controller.signal });

// Später: beide Handler entfernen
setTimeout(() => {
  controller.abort();
  editor.oncompositionupdate = null;
}, 10000);

on-Property: ㅎ Listener: ㅎ compositionupdate

// Wichtig · Fallstricke

Nicht abbrechbar: preventDefault() hat keine Wirkung; die IME-Eingabe lässt sich so nicht unterdrücken.
event.data enthält den gesamten aktuellen Kompositionsstring, nicht nur das neue Zeichen. Wer das Delta braucht, muss es selbst berechnen.
Die Reihenfolge relativ zu input/beforeinput und keydown (bei IME oft key === "Process", keyCode 229) unterscheidet sich zwischen Browsern und Betriebssystemen. Prüfe in input-Handlern lieber event.isComposing.
Auf Android-Tastaturen (z. B. Gboard) laufen auch lateinische Eingaben oft als Komposition ab – compositionupdate feuert dort also auch bei „normalem“ Tippen mit Autokorrektur.
Die Eigenschaft oncompositionupdate ist nicht in allen Browsern als Handler-Attribut vorhanden (u. a. ältere Chrome-Versionen); addEventListener funktioniert überall.
CompositionEvent.locale ist veraltet und wird von den meisten Browsern nicht befüllt.
Den DOM nicht während der Komposition manipulieren (z. B. value neu setzen) – das bricht die IME-Sitzung in vielen Browsern ab.

Siehe auch

Element: compositionstart Element: compositionend Element: input Element: beforeinput Element: DOMActivate