Learning

Writing to the clipboard: writeText, ClipboardItem, and the activation window

A placeholder lesson on writing to the clipboard: the writeText fast path, the ClipboardItem envelope for richer data, and why writes require a recent user gesture.

Levels: Beginner ~10 min read

Basic

The writeText fast path

For plain text, navigator.clipboard.writeText() is the whole story. Call it from a user gesture handler — a click, a keypress — and the promise resolves once the text lands on the system clipboard. The call does not need to complete inside the handler itself; it needs to be initiated while the transient activation window is still open.

ClipboardItem and richer payloads

Richer writes pass a ClipboardItem to navigator.clipboard.write(). The item maps MIME types to blobs, which is what makes images and custom formats possible. A delayed payload — a promise instead of a blob — lets the page prepare data after the gesture, a pattern used by editors that serialise large documents on demand.

Quick check

An image editor wants to place a PNG on the clipboard. Which call does it make?

const item = new ClipboardItem({ "image/png": blob });
await navigator.clipboard.?([item]);

Key takeaways

Plain text writes: writeText() from inside a user gesture's activation window.
Richer writes: write() with ClipboardItem mapping MIME types to blobs or promises.
Activation is transient: writes that begin too late reject with NotAllowedError.

Was this page helpful?

Yes No

Mark this learning resource complete to track your learning progress.