JavaScript Reference ยท Browser and Web APIs
The Clipboard API
Reference for the JavaScript Clipboard API: writeText(), readText(), ClipboardItem, permissions, secure contexts and a safe copy-button pattern with a fallback.
The Clipboard API lets a page copy text, images and other data to the system clipboard and read it back, through navigator.clipboard. Every method is asynchronous and returns a promise, because the browser may need to ask the user for permission or wait for the operating system.
Writing is easy to allow: most browsers accept writeText() as soon as the user has clicked something on your page. Reading is stricter, because the clipboard can hold passwords or private text; browsers show a permission prompt or only allow a paste the user triggered themselves. The API works only in secure contexts (HTTPS and localhost).
await navigator.clipboard.writeText("Copied from a script"); const text = await navigator.clipboard.readText();
Try it
The live editors on this site run in a sandboxed frame without clipboard permission, so the calls below are expected to be rejected here. The examples catch the error and show how real code should handle it. Copy the code to your own page (served over HTTPS or from localhost) to see it work.
Press Run (or Ctrl + Enter) to see the console output here.
No output.
Syntax
navigator.clipboard.writeText(text) navigator.clipboard.readText() navigator.clipboard.write(items) navigator.clipboard.read() new ClipboardItem(data, options)
| Method | Description |
|---|---|
writeText(text) |
Replaces the clipboard contents with a plain-text string. Returns a promise that fulfills with undefined. |
readText() |
Returns a promise for the clipboard's text. Needs permission or a user-initiated paste. |
write(items) |
Writes an array of ClipboardItem objects, which lets you copy images, HTML or several formats at once. |
read() |
Returns a promise for an array of ClipboardItem objects. Use item.types and item.getType(type) to get a Blob for each format. |
Exceptions: the promises reject with a NotAllowedError DOMException when permission is denied, when the page is not focused, or when no user gesture is present where one is required. read() can also reject with NotFoundError when the clipboard holds nothing readable, and write() rejects with TypeError for unsupported MIME types.
Usage notes
- Call it from a user gesture. Put
writeText()inside aclickorkeydownhandler. Calling it on page load or from a timer is usually rejected. - The document must be focused. If the user has switched to another window, the call fails.
- Always handle rejection. Wrap calls in
try/catchand tell the user what to do instead, such as selecting the text manually. - Reading is sensitive. Do not read the clipboard on load. Read it only after an explicit action such as a "Paste" button, and treat the result as untrusted input.
- Embedded frames need permission. A cross-origin
iframeneedsallow="clipboard-write"(andclipboard-readfor reading) to use the API. - Images are limited. Browsers commonly accept only a few formats such as
image/pngfor writing; convert other images to PNG with a canvas first. - Old fallback.
document.execCommand("copy")after selecting text still works in many browsers, but it is deprecated. Use it only as a fallback. - The
copy,cutandpasteevents fire on the document when the user uses the keyboard or menu. TheirclipboardDataproperty lets you inspect or change what is copied without the async API.
Browser support
writeText() and readText() are supported in all current browsers, but permission rules for reading differ between them. Writing images and several formats with ClipboardItem is less uniform, so check a compatibility table.