|
| 1 | +# Introducing the `clipboardchange` Event: A New Way to Interact with the Clipboard |
| 2 | + |
| 3 | +The `clipboardchange` event is a new web platform feature that allows web applications to respond to changes in the system clipboard in a secure and efficient manner. This document provides an overview of the feature, how to use it, and how you can participate in its development through our Origin Trial. |
| 4 | + |
| 5 | +## The Problem: Inefficient Clipboard Polling |
| 6 | + |
| 7 | +Modern web applications, especially rich text editors and productivity tools, often need to know what *kind* of content is on the clipboard to provide a better user experience. For example, a web-based image editor might want to enable a "Paste" button only when there's an image on the clipboard. |
| 8 | + |
| 9 | +Previously, the only way to achieve this was to repeatedly poll the clipboard using `navigator.clipboard.read()`, which is inefficient and can have a noticeable performance impact. |
| 10 | + |
| 11 | +## The Solution: The `clipboardchange` Event |
| 12 | + |
| 13 | +The `clipboardchange` event provides a much more efficient and privacy-preserving solution. Instead of polling, you can now listen for an event that fires whenever the clipboard's content changes. |
| 14 | + |
| 15 | +### Key Features |
| 16 | + |
| 17 | +* **Efficient:** The event is dispatched by the browser only when a change occurs, eliminating the need for polling loops. |
| 18 | +* **Privacy-Preserving:** For security reasons, the event **does not** expose the actual content of the clipboard. Instead, it provides an array of native MIME types for the available data (e.g., `"text/plain"`, `"image/png"`). |
| 19 | +* **No User Prompts:** Because no sensitive content is exposed, this API does not require a user permission prompt, leading to a smoother user experience. |
| 20 | +* **Focus-Aware:** The event only fires when your document has focus, preventing background pages from snooping on clipboard activity. |
| 21 | +* **Cross-Platform:** Works on all platforms except iOS. |
| 22 | + |
| 23 | +## How to Use It |
| 24 | + |
| 25 | +Using the `clipboardchange` event is as simple as adding an event listener to `navigator.clipboard`: |
| 26 | + |
| 27 | +```javascript |
| 28 | +if ('clipboard' in navigator && 'addEventListener' in navigator.clipboard) { |
| 29 | + navigator.clipboard.addEventListener('clipboardchange', event => { |
| 30 | + console.log('Clipboard content changed!'); |
| 31 | + |
| 32 | + // The event.types property contains an array of MIME types |
| 33 | + console.log('Available MIME types:', event.types); |
| 34 | + |
| 35 | + // Example: Enable a "Paste Image" button if a PNG is on the clipboard |
| 36 | + const pasteImageButton = document.getElementById('paste-image-button'); |
| 37 | + if (event.types.includes('image/png')) { |
| 38 | + pasteImageButton.disabled = false; |
| 39 | + } else { |
| 40 | + pasteImageButton.disabled = true; |
| 41 | + } |
| 42 | + }); |
| 43 | +} else { |
| 44 | + console.log('The clipboardchange event is not supported in this browser.'); |
| 45 | +} |
| 46 | +``` |
| 47 | + |
| 48 | +## Availability: Try it with Origin Trials! |
| 49 | + |
| 50 | +The `clipboardchange` event is currently available as an [Origin Trial](https://developer.chrome.com/docs/web-platform/origin-trials/) in Chrome and Microsoft Edge versions 140-142. This allows you to use the feature on your production site and provide valuable feedback to browser vendors before it's finalized. |
| 51 | + |
| 52 | +To participate, you'll need to: |
| 53 | +1. **Register for the Origin Trial:** [Link to your Origin Trial registration page will go here]. |
| 54 | +2. **Add the Origin Trial Token:** Once you have your token, add it to your pages via a `<meta>` tag or an HTTP header. |
| 55 | + |
| 56 | +```html |
| 57 | +<!-- Example of adding the token via a meta tag --> |
| 58 | +<meta http-equiv="origin-trial" content="YOUR_TOKEN_HERE"> |
| 59 | +``` |
| 60 | + |
| 61 | +We encourage you to try it out and see how it can improve your application! |
| 62 | + |
| 63 | +## Provide Feedback |
| 64 | + |
| 65 | +Your feedback is crucial to the development of this feature. If you encounter any issues, have suggestions, or want to share how you're using the `clipboardchange` event, please: |
| 66 | + |
| 67 | +**Log an issue here:** [https://github.com/w3c/clipboard-apis/issues](https://github.com/w3c/clipboard-apis/issues) |
| 68 | + |
| 69 | +We look forward to hearing from you! |
| 70 | + |
| 71 | +## Further Reading and References |
| 72 | + |
| 73 | +* [Explainer Document](./clipboard-change-event-explainer.md) |
| 74 | +* [Chrome Platform Status Entry](https://chromestatus.com/feature/5085102657503232) |
| 75 | +* [W3C Specification Proposed Changes (PR)](https://github.com/w3c/clipboard-apis/pull/239) |
| 76 | +* [W3C Specification (Current Editor's Draft)](https://w3c.github.io/clipboard-apis/#clipboard-event-clipboardchange) |
0 commit comments