Element: paste — Ereignis · JavaScript-Referenz

Signatur

element.addEventListener("paste", handler)

Beschreibung

Das paste-Ereignis gehört zur Clipboard API. Es wird am fokussierten Element ausgelöst, sobald der Benutzer Inhalte aus der Zwischenablage einfügen will, etwa per Tastenkürzel, über das Kontextmenü oder das Browser-Menü. Das Ereignis ist ein ClipboardEvent. Es steigt im DOM auf (Bubbling), lässt sich abbrechen und ist composed.

Über event.clipboardData (ein DataTransfer-Objekt) liest du den Inhalt der Zwischenablage. Mit getData("text/plain") oder getData("text/html") bekommst du Text, über clipboardData.items bzw. clipboardData.files auch Dateien wie eingefügte Bilder. Der Zugriff ist nur synchron innerhalb des Handlers möglich.

Normalerweise fügt der Browser den Inhalt an der Cursorposition ein, wenn das Ziel editierbar ist (<input>, <textarea>, contenteditable). Rufst du event.preventDefault() auf, unterbleibt das. So kannst du den Inhalt bereinigen, umwandeln oder selbst einfügen. Typische Anwendungen: HTML beim Einfügen in reinen Text umwandeln, Bilder per Einfügen hochladen, Eingaben prüfen oder Leerzeichen entfernen.

Ist das Ziel nicht editierbar, wird das Ereignis trotzdem ausgelöst. Es startet dann am fokussierten Element oder an document.body. Einen Handler kannst du mit addEventListener("paste", …) oder über die Eigenschaft onpaste registrieren.

Parameter

Name	Typ	Default	Beschreibung
$type Pflicht	string		Der Ereignisname `"paste"`.
$handler Pflicht	(event: ClipboardEvent) => void		Callback, das ein `ClipboardEvent` erhält. Über `event.clipboardData` liest du den Inhalt der Zwischenablage.
$options	boolean \| AddEventListenerOptions	false	Optionen wie `capture`, `once`, `passive` oder `signal`. Achtung: Bei `passive: true` hat `preventDefault()` keine Wirkung.

Rückgabewert

Typ

void

Beschreibung

addEventListener hat keinen Rückgabewert. Der Handler erhält ein ClipboardEvent.

Beispiele

Eingefügten Text in Großbuchstaben umwandeln

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

input.addEventListener('paste', (event) => {
  event.preventDefault(); // Standard-Einfügen verhindern
  const text = event.clipboardData.getData('text/plain');
  const cleaned = text.trim().toUpperCase();

  // An der Cursorposition einfügen
  const { selectionStart: start, selectionEnd: end, value } = input;
  input.value = value.slice(0, start) + cleaned + value.slice(end);
  input.setSelectionRange(start + cleaned.length, start + cleaned.length);
  console.log('Eingefügt:', cleaned);
});

Eingefügt: ABC-123

Nur reinen Text in contenteditable einfügen

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

editor.addEventListener('paste', (event) => {
  event.preventDefault();
  const text = event.clipboardData.getData('text/plain');
  const selection = window.getSelection();
  if (!selection.rangeCount) return;

  const range = selection.getRangeAt(0);
  range.deleteContents();
  const node = document.createTextNode(text);
  range.insertNode(node);
  range.setStartAfter(node);
  range.collapse(true);
  selection.removeAllRanges();
  selection.addRange(range);
});

Eingefügte Bilder als Vorschau anzeigen

document.addEventListener('paste', (event) => {
  const images = [...event.clipboardData.items]
    .filter((item) => item.kind === 'file' && item.type.startsWith('image/'))
    .map((item) => item.getAsFile());

  for (const file of images) {
    const img = document.createElement('img');
    img.src = URL.createObjectURL(file);
    img.onload = () => URL.revokeObjectURL(img.src);
    document.body.append(img);
    console.log(`Bild eingefügt: ${file.type}, ${file.size} Bytes`);
  }
});

Bild eingefügt: image/png, 48213 Bytes

onpaste-Eigenschaft und removeEventListener

const field = document.querySelector('#passwort-wiederholen');

// Variante 1: on-Property
field.onpaste = (event) => {
  event.preventDefault();
  console.log('Bitte Passwort manuell eingeben.');
};

// Variante 2: Listener entfernbar registrieren
const logPaste = (event) => console.log('Paste:', event.clipboardData.getData('text'));
field.addEventListener('paste', logPaste);
// später:
field.removeEventListener('paste', logPaste);
field.onpaste = null;

Bitte Passwort manuell eingeben.

// Wichtig · Fallstricke

Nur synchroner Zugriff: event.clipboardData ist nur während des Handlers lesbar. Nach einem await oder in einem setTimeout liefert getData() leere Werte. Hole die Daten daher zuerst und verarbeite sie danach asynchron.
Sicherheit (XSS): Inhalte aus getData("text/html") sind nicht vertrauenswürdig. Füge sie nie ungeprüft per innerHTML ein. Bereinige sie vorher, z. B. mit DOMPurify oder der Sanitizer API, oder nutze nur text/plain mit textContent bzw. createTextNode.
Selbst erzeugte Ereignisse: Ein mit new ClipboardEvent("paste") erzeugtes und per dispatchEvent ausgelöstes Ereignis fügt nichts ein und liest die echte Zwischenablage nicht. document.execCommand("paste") ist veraltet und in normalen Webseiten meist blockiert.
Barrierefreiheit: Einfügen in Passwort- oder Bestätigungsfelder zu blockieren, stört Nutzer von Passwort-Managern und gilt als schlechte Praxis.
Formate: Welche Typen clipboardData.types enthält, hängt von Browser und Betriebssystem ab. Dateien aus dem Dateimanager kommen nicht überall an, Bilder aus Screenshots in modernen Browsern schon.
Kompatibilität: Das Ereignis wird in allen modernen Browsern unterstützt. Für programmatisches Lesen außerhalb eines Ereignisses gibt es die asynchrone API navigator.clipboard.read() bzw. readText(). Sie braucht einen sicheren Kontext (HTTPS) und je nach Browser eine Berechtigung.

Siehe auch

ClipboardEvent ClipboardEvent.clipboardData DataTransfer.prototype.getData() Clipboard.prototype.readText() Element: cut