Web APIsBaseline · Widely

Async Clipboard API and User Activation

Mental Model

navigator.clipboard replaces synchronous document.execCommand('copy') with an async, permission-gated OS pasteboard bridge. Writes and reads require HTTPS, document focus, and a live transient user activation token minted by a trusted user event.

Interactive Simulator

Async Copy: Expired Gesture vs Promise-Backed ClipboardItem

Lines of Code
Before
4
After
6
Reflows / Browser Cost
Before
NotAllowedError
After
Gesture Preserved
BeforeAwait Fetch Before writeText() (Fails in Safari)
btn.onclick = async () => {
  const url = await fetchShareUrl();
  await navigator.clipboard.writeText(url); // Activation expired!
};
Lines: 4Reflows: NotAllowedErrorDependencies: 0 kB

Fails when fetch() exceeds the transient activation window.

After (Native)Synchronous ClipboardItem with Promise<Blob>
btn.onclick = () => {
  const item = new ClipboardItem({
    'text/plain': fetchShareUrl().then((u) => new Blob([u], { type: 'text/plain' })),
  });
  navigator.clipboard.write([item]);
};
Lines: 6Reflows: Gesture PreservedDependencies: 0 kB

write() runs synchronously inside the click handler; browser awaits the Blob.

Under the Hood

Transient user activation behaves like a stamped museum entry ticket that dissolves after a few seconds: if you call navigator.clipboard.write() while holding the ticket, the browser keeps the turnstile open while your Promise<Blob> resolves.

  1. Activation Check: Trusted pointer or keyboard events propagating through DOM Event Propagation set the frame's transientActivation timestamp.
  2. Deferred ClipboardItem: Passing a Promise<Blob> inside new ClipboardItem({ 'text/plain': promise }) lets write() claim the gesture synchronously before network I/O completes.
  3. Payload Sanitization: Engines re-encode image/png and strip <script> tags from text/html on paste to neutralize OS-level parser exploits.
JS
button.addEventListener('click', () => {
  const textBlob = fetch('/api/share-link')
    .then((res) => res.text())
    .then((url) => new Blob([url], { type: 'text/plain' }));

  navigator.clipboard.write([new ClipboardItem({ 'text/plain': textBlob })]);
});

Problem Genealogy

  • 2000–2015 (document.execCommand('copy')): Required creating an off-screen <textarea>, mutating selection, and triggering Layout Thrashing.
  • 2018 (navigator.clipboard.writeText): Shipped async plain-text writes without DOM selection hacks.
  • 2020+ (Promise-backed ClipboardItem): Solved the async-fetch gesture-expiry trap across Safari, Chromium, and Firefox.

Production Pitfalls

Production Pitfall
  • Awaiting before calling write(): Even a 300ms fetch() before navigator.clipboard.writeText() triggers NotAllowedError in Safari; wrap the fetch() inside ClipboardItem.
  • Unfocused document or iframe: Calling clipboard methods inside an iframe without allow="clipboard-write" or while DevTools holds focus throws NotAllowedError.
When Not to Use
  • When not to use navigator.clipboard.readText(): Never poll clipboard contents on focus; it triggers intrusive browser permission prompts and erodes user trust.

Connections & Logical Next Steps

Web APIsAsync Clipboard API and User Activation
What This Unlocks
Leaf concept

Mechanical Comparisons