Clipboard API

Reading from and writing to the system clipboard — copy, cut, paste, rich content, and the legacy document.execCommand fallback.

What it is, in plain English: The Clipboard API provides modern, permission-based access to the system clipboard. navigator.clipboard.writeText(text) copies text programmatically. navigator.clipboard.readText() reads the clipboard (requires permission). The ClipboardItem interface supports rich content — HTML, images, and custom MIME types. For simple copy-to-clipboard buttons, writeText() is all you need.

Where this bites you

navigator.clipboard only exists in a secure context: HTTPS, or localhost during development. Open the same page over plain HTTP, such as a staging server or your laptop's LAN address on a phone, and navigator.clipboard is undefined. The copy button throws a TypeError, nothing is copied, and the user gets no feedback at all.

const copyBtn = document.querySelector("#copy-btn");
const codeEl  = document.querySelector("pre");

copyBtn.addEventListener("click", async () => {
  await navigator.clipboard.writeText(codeEl.textContent);
  copyBtn.textContent = "✓ Copied!";
});
// page opened over plain HTTP, e.g. http://staging.test (not localhost):
console.log(window.isSecureContext, typeof navigator.clipboard);
// false "undefined"
// click -> TypeError: Cannot read properties of undefined (reading 'writeText')

Copy and paste from JavaScript

Copy text to clipboard

// The simplest pattern — copy any text:
async function copyText(text) {
  try {
    await navigator.clipboard.writeText(text);
    console.log("Copied!");
  } catch (error) {
    console.error("Copy failed:", error);
  }
}

// A copy button that gives feedback:
const copyBtn = document.querySelector("#copy-btn");
const codeEl  = document.querySelector("pre");

copyBtn.addEventListener("click", async () => {
  await navigator.clipboard.writeText(codeEl.textContent);
  copyBtn.textContent = "✓ Copied!";
  setTimeout(() => { copyBtn.textContent = "Copy"; }, 2000);
});

The copyText() helper above at least catches the error, but the button version doesn't. Check window.isSecureContext first, fall back to the legacy execCommand("copy") technique (covered in the Intermediate tab) on plain HTTP, and always tell the user what happened:

const copyBtn = document.querySelector("#copy-btn");
const codeEl  = document.querySelector("pre");

async function copy(text) {
  if (window.isSecureContext && navigator.clipboard) {
    await navigator.clipboard.writeText(text);   // HTTPS or localhost
    return true;
  }
  return legacyCopy(text);                       // plain HTTP: fall back
}

function legacyCopy(text) {
  const el = document.createElement("textarea");
  el.value = text;
  el.style.position = "absolute";
  el.style.left = "-9999px";
  document.body.appendChild(el);
  el.select();
  const ok = document.execCommand("copy");
  document.body.removeChild(el);
  return ok;
}

copyBtn.addEventListener("click", async () => {
  try {
    const ok = await copy(codeEl.textContent);
    copyBtn.textContent = ok ? "✓ Copied!" : "Press Ctrl+C to copy";
  } catch {
    copyBtn.textContent = "Press Ctrl+C to copy";   // never leave the user guessing
  }
  console.log(copyBtn.textContent);
});
// "✓ Copied!"  (on http://staging.test and on localhost)

Reading the clipboard

// Reading requires user permission (browser asks):
async function pasteText() {
  try {
    const text = await navigator.clipboard.readText();
    input.value = text;  // paste into an input
  } catch (error) {
    // User denied or clipboard access not available
    console.error(error.message);
  }
}

// Listen for paste events (no permission needed — user initiates):
document.addEventListener("paste", (event) => {
  const text = event.clipboardData.getData("text/plain");
  console.log("User pasted:", text);
  event.preventDefault();  // prevent default paste behaviour
});

Try It Yourself

// Clipboard API — copy and paste programmatically

// WRITE — copy text to clipboard:
async function copyToClipboard(text) {
  try {
    await navigator.clipboard.writeText(text);
    console.log("Copied to clipboard:", text);
    return true;
  } catch (error) {
    console.error("Copy failed:", error.message);
    return false;
  }
}

// READ — read from clipboard (requires permission):
async function pasteFromClipboard() {
  try {
    const text = await navigator.clipboard.readText();
    console.log("Clipboard contains:", text.slice(0, 50));
    return text;
  } catch (error) {
    // User denied permission or clipboard is empty:
    console.error("Read failed:", error.message);
    return null;
  }
}

// Copy button pattern:
function setupCopyButton(button, getContent) {
  button.addEventListener("click", async () => {
    const content = typeof getContent === "function" ? getContent() : getContent;
    const success = await copyToClipboard(content);

if (success) {
      const original = button.textContent;
      button.textContent = "✓ Copied!";
      button.disabled = true;
      setTimeout(() => {
        button.textContent = original;
        button.disabled = false;
      }, 2000);
    }
  });
}

// Rich content (HTML + plain text):
async function copyHTML(html, plain) {
  const item = new ClipboardItem({
    "text/html":  new Blob([html],  { type: "text/html" }),
    "text/plain": new Blob([plain], { type: "text/plain" }),
  });
  await navigator.clipboard.write([item]);
  console.log("Rich content copied");
}

// Demo:
copyToClipboard("Hello from The Codex! 🎉");
console.log("Copy function ready — clipboard.writeText() called");

Rich content and the legacy fallback

// ClipboardItem — copy HTML and images:
async function copyAsHTML(html) {
  const blob = new Blob([html], { type: "text/html" });
  await navigator.clipboard.write([new ClipboardItem({ "text/html": blob })]);
}

// Copy an image:
async function copyImage(imageUrl) {
  const res  = await fetch(imageUrl);
  const blob = await res.blob();  // should be image/png
  await navigator.clipboard.write([new ClipboardItem({ "image/png": blob })]);
}

// Listen for clipboard changes (limited browser support):
navigator.clipboard.addEventListener?.("clipboardchange", async () => {
  const text = await navigator.clipboard.readText();
  console.log("Clipboard changed:", text);
});

// Legacy fallback (no async, works on older browsers):
function legacyCopy(text) {
  const el = document.createElement("textarea");
  el.value = text;
  el.style.position = "absolute";
  el.style.left = "-9999px";
  document.body.appendChild(el);
  el.select();
  document.execCommand("copy");  // deprecated but still widely supported
  document.body.removeChild(el);
}

Permissions and Clipboard spec

The Clipboard API (W3C Clipboard API and events spec) requires the document to be focused and the page to have received recent user interaction for read operations. The clipboard-read and clipboard-write permissions are defined in the Permissions API spec. write() (without Text) requires the clipboard-write permission in Chrome but is auto-granted on user gesture. Sanitisation: browsers sanitise HTML on clipboard write to prevent XSS — injected script tags are stripped.

// Check permission state explicitly:
const readPerm  = await navigator.permissions.query({ name: "clipboard-read" });
const writePerm = await navigator.permissions.query({ name: "clipboard-write" });
console.log("Read:", readPerm.state, "Write:", writePerm.state);

Official Sources

The Codex links only to official documentation and the ECMAScript specification. No third-party tutorials.