clipboard-polyfill
Make copying on the web as easy as:
clipboard.writeText("hello world");
As of October 2017, this library is a polyfill for the modern Promise-based asynchronous clipboard API.
(Note: the core library doesn't modify global objects, so it's actually a ponyfill.)
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. (Read to the end of this document for all the limitations.)
See this presentation for for a longer history of clipboard access on the web.
Note: If you only need to copy text and want a super simple polyfill that gets you 80% of the way, consider using this gist.
Get the Code
Get the code using one of the following. If you don't know how to pick and want maximum browser compatibility, start by using "With Promise Polyfill".
Without Promise Polyfill
This version is smaller, but does not work in Internet Explorer unless you add your own Promise polyfill (see below).
- Download
clipboard-polyfill.jsand include it using a<script>tag. npm install clipboard-polyfilland one of:import * as clipboard from "clipboard-polyfill"const clipboard = require("clipboard-polyfill");
With Promise Polyfill
This version works "out of the box" in all browsers that support copying to the clipboard, but is larger.
- Download
clipboard-polyfill.promise.jsand include it using a<script>tag. npm install clipboard-polyfilland one of:import * as clipboard from "clipboard-polyfill/dist/clipboard-polyfill.promise"const clipboard = require("clipboard-polyfill/dist/clipboard-polyfill.promise");
Note: the Promise polyfill in this build version will modify the global object.
Which One?
The async clipboard API design uses ES6 Promise, which is not supported in Internet Explorer. If you want the clipboard-polyfill to work in as many browsers as possible, you will need to include a polyfill for Promise. You can do this by either using the "With Promise Polyfill" version, or by using the "Without Promise Polyfill" version with a polyfill of your own choice. Recommendations include es6-promise and core-js. Instructions for how to use these polyfills are dependent on your build system and can be found in the READMEs of these libraries.
Usage
Plain Text
Copy text to the clipboard (all modern browsers):
clipboard.writeText("This text is plain.");
Read text from the clipboard (IE 9-11 and Chrome 65+):
clipboard.readText().then(console.log, console.error);
Caveats:
- Browsers may require a user gesture or user permission to access the clipboard. In particular, you should write text only in response to an event listener, e.g. a button click listener.
- Reading fails if the clipboard does not contain
text/plaindata.
Other Data Types (e.g. HTML)
Write (all modern browsers):
var dt = new clipboard.DT();
dt.setData("text/plain", "Fallback markup text.");
dt.setData("text/html", "<i>Markup</i> <b>text</b>.");
clipboard.write(dt);
Read (IE 9-11, Chrome 65+):
// The success callback receives a clipboard.DT object.
clipboard.read().then(console.log, console.error);
Caveats:
- Currently,
text/plainandtext/htmlare the only data types that can be written to the clipboard across most browsers. - Unsupported data types will be silently dropped. In general, it is not possible to tell which data types will be dropped.
- This part of the clipboard API is still under active discussion, and may change.
- Currently, reading will only return the
text/plaindata type, if it is on the clipboard.
Interface
clipboard {
static write: (data: clipboard.DT) => Promise<void>
static writeText: (s: string) => Promise<void>
static read: () => Promise<clipboard.DT>
static readText: () => Promise<string>
static suppressWarnings: () => void
}
clipboard.DT {
constructor()
setData: (type: string, value: string): void
getData: (type: string): string