An introduction to the new Async Clipboard API 🔥

A consistent api for clipboard actions outside of document.execCommand has been desired for a while, however various security concerns (sniffing, overwriting, etc.) has made moving the needle on this slow, but alas we now have an obvious winner! Before diving deeper into this, I would like to go over how you would access the clipboard today. Keep in mind that there are other ways and hacks developers have used, especially to support older browsers such as using Flash, etc. However, this introduces other problems and is not ideal.

If you’ve ever tried to access the system clipboard, you know that doing so is usually an ugly combination of using multiple web APIs.

Here is what “The Old” way looks like:

The Old

Usually, the first step involves using the document.execCommand method. When run, this method applies a command to the selected text, which brings us to the second part: The Selection API. Combining the two is what we would need to do in order to copy some text from the DOM to a user’s clipboard.

Click here for a jsfiddle of what that might look like in your app.

Preview GIF of the copy to clipboard example.

Note: make sure to check which browsers you need to target, For example, on IE the above is only supported in IE10 and above.

The New 🔥

Now let’s dive into the new Async Clipboard API. How exactly is it making this much nicer?

First of all, a general overview of the API.

  1. It adds a new object to navigator.clipboard.
  2. A new clipboardchange event to detect clipboard changes.
  3. It provides async methods for reading/writing clipboard data that return promises.

"clipboardchange" event

The new clipboardchangeevent is pretty straightforward. This event fires whenever the clipboard contents are changed. If the clipboard contents are changed outside of the browser, then this event fires when the browser regains focus.

This is what it looks like:

Image of the clipboardchange event.

I can already think of some potential use cases for this. Let’s say you were building an app that reads a user’s clipboard in order to automate documentation or you wanted to build a chrome extension to save multiple distinct clipboard actions the user has performed so that they can refer to it at a later time then this event will be very useful. Another use case could be for you to do some pre-processing on certain clipboard content (e.g: pre fetching certain things, that could be interesting!).

Async, promise based methods for reading/writing to the clipboard.

As discussed, the read and write both return a Promise<DataTransfer> .

Here’s what reading from the clipboard looks like:

Or using async/await 😍

And by now you’ve probably figured out that writing to the clipboard will look very similar:

A few closing notes

  • You can only use the clipboard API in localhost or a secure connection (https)
  • You can find the full spec here.
  • For chrome users, this will only be landing in chrome 66+ so don’t go refactoring all your document.execCommand calls yet. You are probably still better off using something like this for now.
  • Because of potential abuse, you will need to get the user’s permission in order for them to give you access to their clipboard.. Make sure to read this if you’d like a better understanding of clipboard permissions.

That’s it! It’s still early but looks very promising and I think we can all agree that we would like to see this adopted in all browsers so that we can start handling clipboard actions in a sane way and without third-party libraries.

Please feel free to leave feedback or contact me directly if you have any questions.