Async Clipboard API and User Activation
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.
Async Copy: Expired Gesture vs Promise-Backed ClipboardItem
btn.onclick = async () => {
const url = await fetchShareUrl();
await navigator.clipboard.writeText(url); // Activation expired!
};Fails when fetch() exceeds the transient activation window.
btn.onclick = () => {
const item = new ClipboardItem({
'text/plain': fetchShareUrl().then((u) => new Blob([u], { type: 'text/plain' })),
});
navigator.clipboard.write([item]);
};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.
- Activation Check: Trusted pointer or keyboard events propagating through DOM Event Propagation set the frame's
transientActivationtimestamp. - Deferred
ClipboardItem: Passing aPromise<Blob>insidenew ClipboardItem({ 'text/plain': promise })letswrite()claim the gesture synchronously before network I/O completes. - Payload Sanitization: Engines re-encode
image/pngand strip<script>tags fromtext/htmlon paste to neutralize OS-level parser exploits.
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
- Awaiting before calling
write(): Even a 300msfetch()beforenavigator.clipboard.writeText()triggersNotAllowedErrorin Safari; wrap thefetch()insideClipboardItem. - Unfocused document or iframe: Calling clipboard methods inside an iframe without
allow="clipboard-write"or while DevTools holds focus throwsNotAllowedError.
- 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
Transient user activation is minted by trusted input events dispatching through the DOM.
Clipboard sanitization strips executable markup from pasted HTML rather than blocking scripts via CSP.
sendBeacon dispatches background requests without user gesture, whereas Async Clipboard requires transient user activation.
Mechanical Comparisons
sendBeacon dispatches background requests without user gesture, whereas Async Clipboard requires transient user activation.
Clipboard sanitization strips executable markup from pasted HTML rather than blocking scripts via CSP.