Clipboard.writeText() — Methode · JavaScript-Referenz

Signatur

Clipboard.prototype.writeText(data)

Beschreibung

Mit navigator.clipboard.writeText() kopierst du einen String in die Zwischenablage des Betriebssystems. Die Methode gehört zur asynchronen Clipboard API und ersetzt das veraltete document.execCommand("copy"). Sie ist die richtige Wahl für die typischen „Kopieren“-Schaltflächen, etwa bei Code-Schnipseln, Einladungslinks, API-Schlüsseln oder Gutscheincodes.

Da der Schreibvorgang asynchron läuft, gibt die Methode ein Promise zurück. Du solltest es immer mit await oder .then()/.catch() behandeln, damit du dem Nutzer Rückmeldung geben kannst („Kopiert!“) und Fehler abfängst, zum Beispiel wenn der Browser den Zugriff verweigert.

Die API ist nur in sicheren Kontexten (HTTPS oder localhost) verfügbar. Die meisten Browser verlangen außerdem eine vorübergehende Nutzeraktivierung: Der Aufruf muss direkt aus einem Klick, Tastendruck oder einem ähnlichen Ereignis heraus erfolgen. In Chromium-basierten Browsern ist das Schreiben für das aktive Tab zusätzlich über die Berechtigung clipboard-write geregelt, die meist automatisch erteilt wird.

Parameter

Name	Typ	Default	Beschreibung
$data Pflicht	string		Der Text, der in die Zwischenablage geschrieben wird. Werte, die kein String sind, werden in einen String umgewandelt. Der bisherige Inhalt der Zwischenablage wird ersetzt.

Rückgabewert

Typ

Promise<undefined>

Beschreibung

Ein Promise, das mit undefined erfüllt wird, sobald der Inhalt der Zwischenablage aktualisiert ist. Es wird mit einer DOMException (meist NotAllowedError) abgelehnt, wenn der Schreibzugriff nicht erlaubt ist.

Beispiele

Kopieren-Schaltfläche mit Rückmeldung

const button = document.querySelector('#copy-link');
const input = document.querySelector('#share-url');

button.addEventListener('click', async () => {
  try {
    await navigator.clipboard.writeText(input.value);
    button.textContent = 'Kopiert!';
    setTimeout(() => (button.textContent = 'Link kopieren'), 2000);
  } catch (err) {
    console.error('Kopieren fehlgeschlagen:', err.name, err.message);
    button.textContent = 'Kopieren nicht möglich';
  }
});

Code-Blöcke mit Kopier-Button ausstatten

document.querySelectorAll('pre > code').forEach((codeEl) => {
  const btn = document.createElement('button');
  btn.type = 'button';
  btn.textContent = 'Kopieren';
  btn.addEventListener('click', async () => {
    await navigator.clipboard.writeText(codeEl.textContent);
    btn.textContent = '✓ Kopiert';
  });
  codeEl.parentElement.append(btn);
});

Wiederverwendbare Hilfsfunktion mit Fallback

const copyText = async (text) => {
  if (navigator.clipboard && window.isSecureContext) {
    await navigator.clipboard.writeText(text);
    return true;
  }
  // Fallback für unsichere Kontexte / alte Browser (veraltet)
  const textarea = document.createElement('textarea');
  textarea.value = text;
  textarea.setAttribute('readonly', '');
  textarea.style.position = 'fixed';
  textarea.style.opacity = '0';
  document.body.append(textarea);
  textarea.select();
  const ok = document.execCommand('copy');
  textarea.remove();
  return ok;
};

document.querySelector('#copy-coupon').addEventListener('click', async () => {
  const ok = await copyText('SOMMER2024');
  console.log(ok ? 'Gutscheincode kopiert' : 'Kopieren fehlgeschlagen');
});

Gutscheincode kopiert

// Wichtig · Fallstricke

Nur in sicheren Kontexten: Auf reinen HTTP-Seiten ist navigator.clipboard undefined. Vor dem Aufruf per window.isSecureContext oder 'clipboard' in navigator prüfen.
Nutzeraktivierung nötig: Safari und Firefox lehnen Aufrufe außerhalb eines Nutzerereignisses mit NotAllowedError ab. Wenn du vorher lange mit await wartest (z. B. auf fetch), kann die Aktivierung verfallen. In Safari hilft dann navigator.clipboard.write() mit einem ClipboardItem, dem man ein Promise übergibt.
Dokumentfokus: Chromium lehnt ab, wenn das Dokument keinen Fokus hat (Document is not focused), etwa bei Aufrufen aus der geöffneten DevTools-Konsole.
iframes: In eingebetteten Frames muss das Attribut allow="clipboard-write" gesetzt sein (Permissions Policy).
Nur Klartext: Für HTML oder Bilder nutzt du Clipboard.write() mit ClipboardItem.
Sicherheit: Kopiere keine sensiblen Daten ungefragt. Andere Anwendungen und Zwischenablage-Verläufe des Betriebssystems können den Inhalt mitlesen.

Siehe auch

Clipboard Clipboard.readText() Clipboard.write() Clipboard.read() Navigator.clipboard Document.execCommand()