clipboard-polyfill
Make copying on the web as easy as:
clipboard.writeText("This text is plain.");
As of October 2017, this library is a polyfill for the modern Promise
-based asynchronous clipboard API.
Usage
Get the source using one of the following:
- Download
build/clipboard-polyfill.js
and include it using a<script>
tag. npm install clipboard-polyfill
Write / Copy
Copy text:
clipboard.writeText("hello world");
Copy other data types:
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);
Since copying only works in a user gesture, you should attempt it from inside an event listener, e.g. a button click listener.
Read / Paste
Read text:
// The success callback receives a string.
// Fails if the clipboard does not contain `text/plain` data.
clipboard.readText().then(console.log, console.error);
Read all data types:
// The success callback receives a clipboard.DT object.
clipboard.read().then(console.log, console.error);
Note that reading currently only works in Internet Explorer.
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 | undefined
}
clipboard.DT
A note on The asynchronous clipboard API works like this:
var dt = new DataTransfer();
dt.setData("text/plain", "plain text");
navigator.clipboard.write(dt);
Ideally, clipboard-polyfill
would take a DataTransfer
, so that the code above works verbatim when you replace navigator.clipboard
with clipboard
. However, the DataTransfer
constructor cannot be called in most browsers. Thus, this library uses a light-weight alternative to DataTransfer
, exposed as clipboard.DT
:
var dt = new clipboard.DT();
dt.setData("text/plain", "plain text");
clipboard.write(dt);
This is way too complicated!
Try this gist for a simpler solution.
Can I use it?
- Chrome 42+
- Firefox 41+
- Opera 29+
- Internet Explorer 9+ (text only)
- Edge
- Desktop Safari 10+
- iOS Safari 10+ (text only)
clipboard-polyfill
uses a variety of heuristics to get around compatibility bugs. Please let us know if you are running into compatibility issues with any of the browsers listed above.
Limitations
- In Microsoft Edge, it seems to be impossible to detect whether the copy action actually succeeded (Edge Bug #14110451, Edge Bug #14080262).
clipboard-polyfill
will always callresolve()
in Edge. - In Microsoft Edge, only the first data type you specify is copied to the clipboard (Edge Bug #14080506).
DataTransfer
andclipbard.DT
keep track of the order in which you set items. If you care which data type Edge copies, callsetData()
with that data type first.
- On iOS Safari (WebKit Bug #177715) and Internet Explorer, only text copying works.
- On iOS Safari,
clipboard-polyfill
needs to use the DOM to copy, so the text will be copied as rich text.clipboard-polyfill
attempts to use shadow DOM in order to avoid some of the page formatting (e.g. background color) from affecting the copied text. However, such formatting might be copied if shadow DOM is not available. - In other browsers, writing copy data that does not include the
text/plain
data type will succeed, but also show a console warning:
- On iOS Safari,
clipboard.write() was called without a
text/plain
data type. On some platforms, this may result in an empty clipboard. Call clipboard.suppressWarnings() to suppress this warning.
clipboard-polyfill
attemps to avoid changing the document selection or modifying the DOM. However,clipboard-polyfill
will automatically fall back to using them if needed:- On iOS Safari, the user's current selection will be cleared. This should not happen on other platforms unless there are unanticipated bugs. (Please file an issue if you observe this!)
- On iOS Safari and under certain conditions on desktop Safari (WebKit Bug #177715),
clipbard-polyfill
needs to add a temporary element to the DOM. This will trigger a mutation observer if you have attached one todocument.body
. Please file an issue if you'd like to discuss how to detect temporary elements added byclipboard-polyfill
.
read()
currently only works in Internet Explorer.- Internet Explorer can only read
text/plain
values from the clipboard.
- Internet Explorer can only read
- Internet Explorer does not have a native
Promise
implementation, so the standalone build file forclipboard-polyfill
also includesstefanpenner
'ses6-promise
polyfill. This adds significant size to the build. Please file an issue if you're interested in a minimal build without Internet Explorer support.