Skip to content

lgarron/clipboard-polyfill

main
Switch branches/tags

Name already in use

A tag already exists with the provided branch name. Many Git commands accept both tag and branch names, so creating this branch may cause unexpected behavior. Are you sure you want to create this branch?
Code

Latest commit

Release notes:

- `clipboard-polyfill` is entering maintenance mode. I do not expect to add new features, and most modern projects will no longer need this library. Thanks for filing issues documenting remaining use cases: https://github.com/lgarron/clipboard-polyfill#%EF%B8%8F-you-dont-need-clipboard-polyfill-to-copy-text-%EF%B8%8F
- The build system has been overhauled to use `esbuild`. I've tested compatibility all the way back to IE10, and this will hopefully make the project more maintainable in the future. Please let me know if if you encounter any compatibility issues.
- `writeText(…)` now tries more fallbacks even if the `navigator.clipboard.writeText(…)` API is available. This should succeed in some environments where permissions are not consistently enforced.
- We no longer publish minified and/or CommonJS builds. If you need these, see: https://github.com/lgarron/clipboard-polyfill#bundling--tree-shaking--minification--commonjs
- The main build uses ESM with module splitting, so there is no longer a text-only build. Please import `writeText(…)` from `clipboard-polyfill` directly. For a tree-shaken text-only build, also see: https://github.com/lgarron/clipboard-polyfill#bundling--tree-shaking--minification--commonjs
c24845e

Git stats

Files

Permalink
Failed to load latest commit information.
Type
Name
Latest commit message
Commit time
 
 
 
 
src
 
 
 
 
 
 
 
 
 
 
 
 

Logo for clipboard-polyfill: an icon of a clipboard fading into a drafting paper grid.

clipboard-polyfill

⚠️ You don't need clipboard-polyfill to copy text! ⚠️

Note: As of 2020, you can use navigator.clipboard.writeText(...) in the stable versions of all major browsers. This library will only be useful to you if you want to:

  • target older browsers (see below for compatibility) for text copy,
  • copy text/html in Firefox,
  • use the ClipboardItem API in Firefox, or
  • polyfill the API shape in a non-browser environment (e.g. in jsdom).

See the Compatibility section below for more details.


Summary

Makes copying on the web as easy as:

clipboard.writeText("hello world");

This library is a ponyfill/polyfill for the modern Promise-based asynchronous clipboard API.

Usage

If you use npm, install:

npm install clipboard-polyfill

Sample app that copies text to the clipboard:

import * as clipboard from "clipboard-polyfill";

function handler() {
  clipboard.writeText("This text is plain.").then(
    () => { console.log("success!"); },
    () => { console.log("error!"); }
  );
}

window.addEventListener("DOMContentLoaded", function () {
  const button = document.body.appendChild(document.createElement("button"));
  button.textContent = "Copy";
  button.addEventListener("click", handler);
});

Notes:

  • You need to call a clipboard operation in response to a user gesture (e.g. the event handler for a button click).
    • Some browsers may only allow one clipboard operation per gesture.

async/await syntax

import * as clipboard from "clipboard-polyfill";

async function handler() {
  console.log("Previous clipboard text:", await clipboard.readText());

  await clipboard.writeText("This text is plain.");
}

window.addEventListener("DOMContentLoaded", function () {
  const button = document.body.appendChild(document.createElement("button"));
  button.textContent = "Copy";
  button.addEventListener("click", handler);
});

More MIME types (data types)

import * as clipboard from "clipboard-polyfill";

async function handler() {
  console.log("Previous clipboard contents:", await clipboard.read());

  const item = new clipboard.ClipboardItem({
    "text/html": new Blob(
      ["<i>Markup</i> <b>text</b>. Paste me into a rich text editor."],
      { type: "text/html" }
    ),
    "text/plain": new Blob(
      ["Fallback markup text. Paste me into a rich text editor."],
      { type: "text/plain" }
    ),
  });
  await clipboard.write([item]);
}

window.addEventListener("DOMContentLoaded", function () {
  const button = document.body.appendChild(document.createElement("button"));
  button.textContent = "Copy";
  button.addEventListener("click", handler);
});

Check the Clipboard API specification for more details.

Notes:

  • You'll need to use async functions for the await syntax.
  • Currently, text/plain and text/html are the only data types that can be written to the clipboard across most browsers.
  • If you try to copy unsupported data types, they may be silently dropped (e.g. Safari 13.1) or the call may throw an error (e.g. Chrome 83). In general, it is not possible to tell when data types are dropped.
  • In some current browsers, read() may only return a subset of supported data types, even if the clipboard contains more data types. There is no way to tell if there were more data types.

overwrite-globals version

If you want the library to overwrite the global clipboard API with its implementations, import clipboard-polyfill/overwrite-globals. This will turn the library from a ponyfill into a proper polyfill, so you can write code as if the async clipboard API were already implemented in your browser:

import "clipboard-polyfill/overwrite-globals";

async function handler() {
  const item = new window.ClipboardItem({
    "text/html": new Blob(
      ["<i>Markup</i> <b>text</b>. Paste me into a rich text editor."],
      { type: "text/html" }
    ),
    "text/plain": new Blob(
      ["Fallback markup text. Paste me into a rich text editor."],
      { type: "text/plain" }
    ),
  });

  navigator.clipboard.write([item]);
}

window.addEventListener("DOMContentLoaded", function () {
  const button = document.body.appendChild(document.createElement("button"));
  button.textContent = "Copy";
  button.addEventListener("click", handler);
});

This approach is not recommended, because it may break any other code that interacts with the clipboard API globals, and may be incompatible with future browser implementations.

Flat-file version with Promise included

If you need to grab a version that "just works", download clipboard-polyfill.window-var.promise.es5.js and include it using a <script> tag:

<script src="./clipboard-polyfill.window-var.promise.es5.js"></script>
<button onclick="copy()">Copy text!</button>
<script>
  // `clipboard` is defined on the global `window` object.
  function copy() {
    clipboard.writeText("hello world!");
  }
</script>

Bundling / tree shaking / minification / CommonJS

Thanks to the conveniences of the modern JS ecosystem, we do not provide tree shaken, minified, or CommonJS builds anymore. To get such builds without losing compatibility, pass clipboard-polyfill builds through esbuild. For example:

mkdir temp && cd temp && npm install clipboard-polyfill esbuild

# Minify the ES6 build:
echo 'export * from "clipboard-polyfill";' | npx esbuild --format=esm --target=es6 --bundle --minify

# Include just the `writeText()` export and minify:
echo 'export { writeText } from "clipboard-polyfill";' | npx esbuild --format=esm --target=es6 --bundle --minify

# Minify an ES5 build:
cat node_modules/clipboard-polyfill/dist/es5/window-var/clipboard-polyfill.window-var.promise.es5.js | npx esbuild --format=esm --target=es5 --bundle --minify

# Get a CommonJS build:
echo 'export * from "clipboard-polyfill";' | npx esbuild --format=cjs --target=es6 --bundle

Why clipboard-polyfill?

Browsers have implemented several clipboard APIs over time, and writing to the clipboard without triggering bugs in various old and current browsers is fairly tricky. In every browser that supports copying to the clipboard in some way, clipboard-polyfill attempts to act as close as possible to the async clipboard API. (See above for disclaimers and limitations.)

See this presentation for for a longer history of clipboard access on the web.

Compatibility

  • ☑️: Browser has native async clipboard support.
  • : clipboard-polyfill adds support.
  • : Support is not possible.
  • Bold browser names indicate the latest functionality changes for stable versions of modern browsers.

Write support by earliest browser version:

Browser writeText() write() (HTML) write() (other formats)
Safari 13.1 ☑️ ☑️ ☑️ (image/uri-list, image/png)
Chrome 86ᵃ / Edge 86 ☑️ ☑️ ☑️ (image/png)
Chrome 76ᵃ / Edge 79 ☑️ ☑️ (image/png)
Chrome 66ᵃ / Firefox 63 ☑️
Safari 10 / Chrome 42ᵃ / Edgeᵈ / Firefox 41
IE 9

Read support:

Browser readText() read() (HTML) read() (other formats)
Safari 13.1 ☑️ ☑️ ☑️ (image/uri-list, image/png)
Chrome 76 ᵃ / Edge 79 ☑️ ☑️ (image/png)
Chrome 66 ☑️
IE 9
Firefox
  • ᵃ Also includes versions of Edge, Opera, Brave, Vivaldi, etc. based on the corresponding version of Chrome.
  • ᵇ HTML did not work properly on mobile Safari in the first few releases of version 10.
  • ᶜ In Internet Explorer, you will need to polyfill window.Promise if you want the library to work.
  • ᵈ In older versions of Edge (Spartan):
    • It may not be possible to tell if a copy operation succeeded (Edge Bug #14110451, Edge Bug #14080262). clipboard-polyfill will always report success in this case.
    • Only the last data type you specify is copied to the clipboard (Edge Bug #14080506). Consider placing the most important data type last in the object that you pass to the ClipboardItem constructor.
    • The text/html data type is not written using the expected CF_HTML format. clipboard-polyfill does not try to work around this, since 1) it would require fragile browser version sniffing, 2) users of Edge are not generally stuck on version < 17, and 3) the failure mode for other browsers would be that invalid clipboard HTML is copied. (Edge Bug #14372529, #73)

clipboard-polyfill uses a variety of heuristics to work around compatibility bugs. Please let us know if you are running into compatibility issues with any of the browsers listed above.

History

Browser history

Browser First version supporting
navigator.clipboard.writeText(...)
Release Date
Chrome 66+ April 2018
Firefox 53+ October 2018
Edge 79+ (first Chromium-based release) January 2020
Safari 13.1+ March 2020

Project history

This project dates from a time when clipboard access in JS was barely becoming possible, and ergonomic clipboard API efforts were stalling. (See this presentation for a bit more context.) Fortunately, an ergonomic API with the same functionality is now available in all modern browsers since 2020:

Thanks to Gary Kacmarcik, Hallvord Steen, and others for helping to bring the async clipboard API to life!

This is way too complicated!

If you only need to copy text in modern browsers, consider using navigator.clipboard.writeText() directly: https://caniuse.com/mdn-api_clipboard_writetext

If you need copy text in older browsers as well, you could also try this gist for a simple hacky solution.