JavaScript Async Clipboard API Guide

The modern Clipboard API provides a secure, asynchronous interface for web applications to interact directly with the operating system clipboard. Replacing the deprecated document.execCommand() approach, this API uses JavaScript Promises to read and write clipboard data without blocking the main thread or degrading page performance. This guide explains how the Clipboard API functions and provides practical methods for handling both text and images asynchronously.

What is the Clipboard API?

The Clipboard API is exposed through the navigator.clipboard object. Because accessing the system clipboard poses potential privacy risks, the API operates strictly within secure contexts (HTTPS) and requires either an active user gesture—such as a click event—or explicit permissions granted via the Permissions API.

All methods on navigator.clipboard return Promises, allowing operations to execute asynchronously and integrate seamlessly with async/await syntax.

Writing and Reading Text

Text operations are the most common clipboard interactions and have dedicated convenience methods.

Writing Text to the Clipboard

To copy plain text to the clipboard, use the writeText() method:

async function copyText(text) {
  try {
    await navigator.clipboard.writeText(text);
    console.log('Text copied to clipboard successfully.');
  } catch (err) {
    console.error('Failed to copy text: ', err);
  }
}

Reading Text from the Clipboard

To retrieve plain text from the clipboard, use the readText() method:

async function pasteText() {
  try {
    const text = await navigator.clipboard.readText();
    console.log('Pasted text: ', text);
    return text;
  } catch (err) {
    console.error('Failed to read clipboard contents: ', err);
  }
}

Writing and Reading Images

For non-text data formats, such as PNG images, the API provides the generic write() and read() methods, which rely on Blob and ClipboardItem objects.

Writing an Image to the Clipboard

Writing an image requires converting the image data into a Blob, encapsulating it within a ClipboardItem keyed by its MIME type, and passing an array of items to navigator.clipboard.write():

async function copyImage(imageBlob) {
  try {
    const item = new ClipboardItem({ [imageBlob.type]: imageBlob });
    await navigator.clipboard.write([item]);
    console.log('Image copied to clipboard successfully.');
  } catch (err) {
    console.error('Failed to copy image: ', err);
  }
}

Note: Most browsers strictly require image data to be in the image/png format when writing to the clipboard.

Reading an Image from the Clipboard

Reading an image involves retrieving clipboard items with navigator.clipboard.read(), checking the available MIME types, and extracting the corresponding Blob:

async function pasteImage() {
  try {
    const items = await navigator.clipboard.read();
    for (const item of items) {
      if (item.types.includes('image/png')) {
        const blob = await item.getType('image/png');
        console.log('Image retrieved from clipboard:', blob);
        return blob;
      }
    }
    console.log('No PNG image found in clipboard.');
  } catch (err) {
    console.error('Failed to read image from clipboard: ', err);
  }
}

Security and Permission Handling

Reading from the clipboard typically triggers a browser permission prompt to protect sensitive user data. You can query current permissions using the Permissions API before attempting read operations:

async function checkClipboardPermission() {
  const query = await navigator.permissions.query({ name: 'clipboard-read' });
  return query.state; // 'granted', 'prompt', or 'denied'
}

Writing to the clipboard generally does not require explicit permission prompts if the action is triggered directly by a transient user activation, such as clicking a “Copy” button.