Interact with the clipboard

Writing to the clipboard

The Clipboard API methods navigator.clipboard.write() and navigator.clipboard.writeText() write arbitrary content to the clipboard. The methods are available from a secure context but only function after the extension's user performs transient activation. However, with the "clipboardWrite" permission, transient activation isn't required.

This function takes a string and writes it to the clipboard:

function updateClipboard(newClip) {
  navigator.clipboard.writeText(newClip).then(
    () => {
      /* clipboard successfully set */
    },
    () => {
      /* clipboard write failed */
    },
  );
}

Using execCommand()

The "cut" and "copy" commands of the document.execCommand() method are used to replace the clipboard's content with the selected material. Extensions can use these commands without special permission in short-lived event handlers triggered by user actions (for example, a click handler).

For example, suppose you've got a popup that includes this HTML:

<input id="input" type="text" /> <button id="copy">Copy</button>

To make the "copy" button copy the contents of the <input> element, you can use code like this:

function copy() {
  let copyText = document.querySelector("#input");
  copyText.select();
  document.execCommand("copy");
}

document.querySelector("#copy").addEventListener("click", copy);

Because the execCommand() call is inside a click event handler, your extension doesn't need special permissions.

However, take the example of your extension triggering the copy from an alarm:

function copy() {
  let copyText = document.querySelector("#input");
  copyText.select();
  document.execCommand("copy");
}

browser.alarms.create({
  delayInMinutes: 0.1,
});

browser.alarms.onAlarm.addListener(copy);

Depending on the browser, this may not work. On Firefox, it doesn't work, and you see a message like this in the console:

document.execCommand('cut'/'copy') was denied because it was not called from inside a short running user-generated event handler.

To enable this use case, your extension must request the "clipboardWrite" permission: "clipboardWrite" enables your extension to write to the clipboard outside a short-lived event handler for a user action.

Reading from the clipboard

The Clipboard API methods navigator.clipboard.read() and navigator.clipboard.readText() read arbitrary text or binary data from the clipboard. These methods allow extensions to access data in the clipboard without pasting it into an editable element.

The methods are available from a secure context but only function after the extension's user performs transient activation and clicks a paste prompt in an ephemeral context menu. However, with the "clipboardRead" permission, your extension can read from the clipboard without user confirmation or transient activation.

This snippet of code fetches the text from the clipboard and replaces the contents of the element with the ID "outbox" with that text.

navigator.clipboard
  .readText()
  .then((clipText) => (document.getElementById("outbox").innerText = clipText));

Using execCommand()

To use document.execCommand("paste"), your extension needs the "clipboardRead" permission. This requirement exists even if you're using the "paste" command from within a user-generated event handler, such as click or keypress.

Consider HTML that includes this:

<textarea id="output"></textarea> <button id="paste">Paste</button>

To set the content of the <textarea> element with the ID "output" from the clipboard when the user clicks the "paste" <button>, you can use code like this:

function paste() {
  let pasteText = document.querySelector("#output");
  pasteText.focus();
  document.execCommand("paste");
  console.log(pasteText.textContent);
}
document.querySelector("#paste").addEventListener("click", paste);

Browser-specific considerations

In Chrome:

• Chrome doesn't expose navigator.clipboard to extension service workers, and offscreen documents can't access navigator.clipboard due to the API's document focus requirements. As a result, Chrome extensions have to use the deprecated document.execCommand() APIs in an offscreen document or use navigator.clipboard in a different context, such as a content script or extension page. For page scripts to write to the clipboard without user interaction, the "clipboard-write" permission needs to be requested using the Web API navigator.permissions. Your extension can check for that permission using navigator.permissions.query():

  js

  navigator.permissions.query({ name: "clipboard-write" }).then((result) => {
    if (result.state === "granted" || result.state === "prompt") {
      /* write to the clipboard now */
    }
  });
  

  Note: The clipboard-write permission is not supported in Firefox or Safari.

In Firefox:

• The availability of the Clipboard API read methods on the user's response to a paste prompt was introduced for web pages in Firefox 127 and extensions in Firefox 147. Before that, the methods were only available when the "clipboardRead" permission was set.

In Safari:

• The "clipboardWrite" permission is only supported in extension contexts (not content scripts).
• The "clipboardRead" permission isn't support.

Browser compatibility

api.Clipboard

webextensions.api.clipboard

See also

• Clipboard API
• Permissions API
• Make content editable