Clipboard API

Understanding the Clipboard API

The Clipboard API allows webpages to interact with the system clipboard so users can copy or, when permitted, read clipboard content using JavaScript.

The modern Clipboard API is available through navigator.clipboard and provides asynchronous methods for working with clipboard data while respecting browser security and permission requirements.

The Clipboard Object

The modern Clipboard API is accessed through the navigator.clipboard object.

navigator.clipboard

The object provides methods for reading and writing clipboard content. Because clipboard access can affect information outside the webpage, browsers apply security restrictions to these operations.

Copy Text to the Clipboard

The writeText() method copies a string to the user's system clipboard.

navigator.clipboard.writeText("Hello, World!");

A practical example usually performs the copy operation after a user selects a button.

const button = document.querySelector("#copy");

button.addEventListener("click", () => {
  navigator.clipboard.writeText("Hello, World!");
});

After the operation succeeds, the text can be pasted into another input, document, application, or other destination that accepts clipboard text.

Read Text from the Clipboard

The readText() method attempts to retrieve text currently stored on the user's clipboard.

const text = await navigator.clipboard.readText();

Reading clipboard content is generally more restricted than writing text because it can expose information copied from another webpage or application.

Whether reading succeeds depends on the browser, document security, permissions, and the circumstances in which the request is made.

Clipboard Methods Are Asynchronous

Clipboard methods such as writeText() and readText() return promises because clipboard access may require browser processing or permission checks.

navigator.clipboard.writeText("Copied text")
  .then(() => {
    console.log("Text copied.");
  })
  .catch((error) => {
    console.error("Copy failed:", error);
  });

The same operations can be written using async and await.

async function copyText() {
  try {
    await navigator.clipboard.writeText("Copied text");
    console.log("Text copied.");
  } catch (error) {
    console.error("Copy failed:", error);
  }
}

Permissions and Security

Clipboard access is restricted because a webpage could otherwise read information the user copied from another application or silently replace clipboard content.

The modern Clipboard API is intended for secure contexts, which normally means the webpage should be delivered over HTTPS.

Browsers may also require permission or user interaction before allowing certain clipboard operations. Exact behavior can vary between browsers and between reading and writing operations.

User Interaction Requirements

Clipboard operations are most reliable when they occur in response to a clear user action such as selecting a Copy or Paste button.

button.addEventListener("click", async () => {
  await navigator.clipboard.writeText("Copied by the user.");
});

This helps prevent webpages from interacting with the clipboard unexpectedly and makes it clear to the user why the operation is occurring.

Clipboard Events

Browsers also provide clipboard-related events for traditional cut, copy, and paste actions.

These events are different from calling asynchronous Clipboard API methods directly, but both approaches can be useful depending on what a webpage needs to accomplish.

The copy Event

The copy event can be detected when the user copies selected content from the document.

document.addEventListener("copy", () => {
  console.log("Content was copied.");
});

The event can also provide access to clipboard-related event data when a webpage needs to customize copied content, although modifying normal copy behavior should be done only when there is a clear reason.

The paste Event

The paste event occurs when the user pastes clipboard content into the document.

document.addEventListener("paste", (event) => {
  const text = event.clipboardData.getData("text");
  console.log(text);
});

The clipboardData property provides access to the data involved in that particular clipboard event.

Complete Clipboard Example

The following example allows the user to enter text and copy it to the system clipboard. A status message confirms whether the copy operation succeeded.

<label for="text">Text to copy:</label>
<input type="text" id="text" value="Hello from the Clipboard API!">

<button type="button" id="copy">Copy Text</button>

<p id="status"></p>

<script>
const text = document.querySelector("#text");
const copyButton = document.querySelector("#copy");
const status = document.querySelector("#status");

copyButton.addEventListener("click", async () => {
  try {
    await navigator.clipboard.writeText(text.value);
    status.textContent = "Text copied to the clipboard.";
  } catch (error) {
    status.textContent = "Unable to copy the text.";
  }
});
</script>

After selecting Copy Text, the user can paste the copied value into another field, document, or application to confirm that the Clipboard API worked.

Handling Clipboard Errors

Clipboard operations can fail when access is unavailable, permission is denied, the page is not running in an appropriate security context, or browser restrictions prevent the request.

try {
  await navigator.clipboard.writeText("Example text");
} catch (error) {
  console.error("Clipboard access failed:", error);
}

Applications should provide a useful message or alternative when clipboard access fails rather than assuming every request will succeed.

Common Clipboard API Mistakes

Best Practices

• Use clipboard operations in response to clear user actions whenever possible.
• Provide visible feedback when text has been copied successfully.
• Handle rejected promises and unavailable clipboard access.
• Use HTTPS when working with the modern Clipboard API.
• Request clipboard reading only when it is necessary and expected by the user.
• Do not collect or store clipboard content unnecessarily.
• Preserve normal keyboard shortcuts and familiar copy-and-paste behavior.
• Use the asynchronous Clipboard API instead of relying on older deprecated copying techniques.
• Provide an alternative when clipboard access is unavailable.

Summary

The Clipboard API allows webpages to interact with the system clipboard through methods such as writeText() and readText(). These operations are asynchronous and are subject to browser security, permission, and user-interaction requirements.

Clipboard events such as copy, cut, and paste provide another way to respond to traditional clipboard actions. Next, we will look at the Fullscreen API and how webpages can display an element using the browser's fullscreen mode.