Navigator.clipboard — Eigenschaft · JavaScript-Referenz

Signatur

Navigator.clipboard

Beschreibung

navigator.clipboard gibt ein Clipboard-Objekt zurück. Das ist der Einstiegspunkt der asynchronen Clipboard API. Damit lässt sich die Systemzwischenablage lesen und beschreiben, ohne auf das veraltete document.execCommand("copy") zurückzugreifen. Alle Methoden geben ein Promise zurück und blockieren die Seite deshalb nicht.

Die wichtigsten Methoden sind:

writeText(text) schreibt reinen Text in die Zwischenablage.
readText() liest reinen Text aus der Zwischenablage.
write(items) schreibt beliebige Daten als ClipboardItem, z. B. Bilder (image/png) oder HTML.
read() liest alle Einträge als Array von ClipboardItem-Objekten.

Typische Einsatzfälle sind „Kopieren“-Schaltflächen für Code-Schnipsel, Links oder Zugangsdaten, das Einfügen von Bildern in Editoren und Einfüge-Funktionen in Web-Apps. Die Eigenschaft gibt es nur in einem sicheren Kontext (HTTPS oder localhost). Ohne sicheren Kontext ist sie undefined.

Schreiben ist in der Regel nur als Reaktion auf eine Nutzeraktion erlaubt (vorübergehende Nutzeraktivierung, z. B. ein Klick). Lesen verlangt je nach Browser eine Berechtigung (clipboard-read in Chromium) oder eine ausdrückliche Bestätigung über ein Kontextmenü zum Einfügen (Firefox, Safari).

Rückgabewert

Typ

Clipboard | undefined

Beschreibung

Das Clipboard-Objekt des aktuellen Browsing-Kontexts. Außerhalb sicherer Kontexte (HTTP) ist der Wert undefined.

Beispiele

Kopieren-Schaltfläche für ein Code-Schnipsel

const button = document.querySelector('#copy-btn');
const code = document.querySelector('#snippet');

button.addEventListener('click', async () => {
  try {
    await navigator.clipboard.writeText(code.textContent);
    button.textContent = 'Kopiert!';
  } catch (err) {
    console.error('Kopieren fehlgeschlagen:', err.name, err.message);
  }
});

Nach dem Klick steht der Inhalt von #snippet in der Zwischenablage, und die Schaltfläche zeigt „Kopiert!“.

Text aus der Zwischenablage einfügen

const pasteBtn = document.querySelector('#paste-btn');
const input = document.querySelector('#url-input');

pasteBtn.addEventListener('click', async () => {
  try {
    const text = await navigator.clipboard.readText();
    input.value = text.trim();
    console.log('Eingefügt:', input.value);
  } catch (err) {
    // NotAllowedError, wenn der Zugriff verweigert wurde
    console.warn('Lesen nicht erlaubt:', err.name);
  }
});

Eingefügt: https://example.com

Canvas als PNG-Bild kopieren

const canvas = document.querySelector('canvas');

document.querySelector('#copy-image').addEventListener('click', async () => {
  // Blob als Promise übergeben, damit Safari die Nutzeraktivierung nicht verwirft
  const blobPromise = new Promise((resolve) => canvas.toBlob(resolve, 'image/png'));
  const item = new ClipboardItem({ 'image/png': blobPromise });
  await navigator.clipboard.write([item]);
  console.log('Bild kopiert');
});

Bild kopiert

Unterstützung prüfen und auf execCommand zurückfallen

const copyText = async (text) => {
  if (navigator.clipboard?.writeText) {
    await navigator.clipboard.writeText(text);
    return true;
  }
  // Veralteter Weg für unsichere Kontexte oder alte Browser
  const ta = document.createElement('textarea');
  ta.value = text;
  document.body.append(ta);
  ta.select();
  const ok = document.execCommand('copy');
  ta.remove();
  return ok;
};

document.querySelector('#share').addEventListener('click', async () => {
  console.log(await copyText(location.href));
});

true

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Unter http:// (außer localhost) ist navigator.clipboard undefined. Deshalb vorher mit navigator.clipboard?.writeText prüfen.
Nutzeraktivierung: writeText() und write() schlagen außerhalb eines Klick- oder Tastatur-Handlers meist mit NotAllowedError fehl. Das gilt auch, wenn vor dem Aufruf zu lange await-Ketten laufen (besonders in Safari). Daten, die erst noch geladen werden, übergibt man deshalb als Promise an ClipboardItem.
Fokus: In Chromium muss das Dokument den Fokus haben. Wer den Aufruf aus der DevTools-Konsole startet, bekommt oft NotAllowedError: Document is not focused.
Lesen: readText() und read() lösen in Chromium eine Berechtigungsabfrage (clipboard-read) aus. Firefox (seit Version 125) und Safari zeigen stattdessen ein Einfügen-Menü. Die Berechtigungsnamen lassen sich über navigator.permissions.query() nicht in allen Browsern abfragen.
iframes: Eingebettete Dokumente brauchen allow="clipboard-read; clipboard-write" in der Permissions Policy.
MIME-Typen: Zuverlässig funktionieren nur text/plain, text/html und image/png. Andere Formate werden abgelehnt oder brauchen das Präfix web (Web Custom Formats, nur Chromium).
Sicherheit: Eingelesene Inhalte kommen von außen und sind nicht vertrauenswürdig. HTML aus read() daher nie ungefiltert per innerHTML einsetzen, sondern bereinigen (z. B. mit DOMPurify), sonst droht XSS. Außerdem keine sensiblen Daten ungefragt in die Zwischenablage schreiben.
Web Worker: Die Eigenschaft gibt es nur im Fenster-Kontext, nicht in Web Workern.

Siehe auch

Clipboard Clipboard.write() Clipboard.read() Navigator Navigator.keyboard