Skip to content

Commit 2567218

Browse files
authored
[Clipboardchange event API] - Added Readme.md for origin trials and moved all related files to a separate folder (#1108)
* Moved clipboardchange to new folder and added Readme.md * Added release version, spec PR urls, chrome feature url
1 parent 1f4f1e5 commit 2567218

9 files changed

+76
-0
lines changed
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
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)
File renamed without changes.

0 commit comments

Comments
 (0)