FF156 ClipBoard Async API - custom types by hamishwillee · Pull Request #45620 · mdn/content

hamishwillee · 2026-09-11T07:07:56Z

FF156 adds support for the async Clipboard API to use web custom formats.

The API allows you to create a ClipboardItem that contains several representations of a copied object, such as version in HTML and Text, and push it to the system clipboard. Something else can read the clipboard and get back tha object - then choose the best format it understands.

The update allows you to (behind a pref) use other types than PNG, HTML, txt.

What this update does is

make the model above clear, because it wasn't - it referred too much to "arbitrary types" can didn't capture "different representations".
Add information about how to use various types and methods
Extend the API overview to cover the main use cases. One good example.

Related docs work can be tracked in #45430

github-actions · 2026-09-11T07:09:41Z

Preview URLs (6 pages)

(comment last updated: 2026-09-15 08:37:30)

pepelsbey

Looks good! Thank you 🙂

Just a few suggestions and a question.

Josh-Cena · 2026-09-11T21:49:51Z

lmk if I can be of help but looks like the PR is already being reviewed.

Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

hamishwillee · 2026-09-14T01:38:21Z

@pepelsbey I have fixed your suggestions. Ready for another look. I'll build my follow-on PR either on this or in this PR.

pepelsbey

Thanks! A few more notes

Co-authored-by: Vadim Makeev <hi@pepelsbey.dev> Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

hamishwillee · 2026-09-15T08:38:30Z

Thanks @pepelsbey . I fixed your issues and then extended this for the custom types. Everything needed for the docs on this project item in there now. Sorry, review now a bit bigger.

hamishwillee · 2026-09-20T23:40:07Z

@pepelsbey Can you have another check of this please

pepelsbey

Spotted a few more things to fix, nothing major. Otherwise, ready to go!

pepelsbey · 2026-10-03T11:26:31Z

+This lets a web app define its own clipboard format for data that has no standard representation, without colliding with the OS's native clipboard formats or another site's custom formats.
+
+Custom formats are useful because they can preserve information a standard representation can't, for example structured metadata alongside a visual or text version of the same content.
+An app that recognizes its own custom format can paste it with data loss for users who copy from it, while other apps still receive whichever standard representations you also provide.


Suggested change

An app that recognizes its own custom format can paste it with data loss for users who copy from it, while other apps still receive whichever standard representations you also provide.

An app that recognizes its own custom format can paste it without data loss for users who copy from it, while other apps still receive whichever standard representations you also provide.

If I understood it correctly

pepelsbey · 2026-10-03T11:30:03Z

+There is nothing special about the blob for the custom format: the only difference is the`web` prefix used for its key.
+The `text/html` blob omits the `SKU` column stored in the custom format, and acts as a fall back when the content is pasted in apps and browsers that don't allow the format.


Suggested change

There is nothing special about the blob for the custom format: the only difference is the`web` prefix used for its key.

The `text/html` blob omits the `SKU` column stored in the custom format, and acts as a fall back when the content is pasted in apps and browsers that don't allow the format.

There is nothing special about the blob for the custom format: the only difference is the `web` prefix used for its key.

The `text/html` blob omits the `SKU` column stored in the custom format, and acts as a fallback when the content is pasted in apps and browsers that don't support the format.

pepelsbey · 2026-10-03T11:33:03Z

+
+#### HTML
+
+The HTML defines a {{htmlelement("p")}} element for the source text to be copied, {{htmlelement("button")}} elements to copy and paste the text, and an element into which the the text will be copied .


Suggested change

The HTML defines a {{htmlelement("p")}} element for the source text to be copied, {{htmlelement("button")}} elements to copy and paste the text, and an element into which the the text will be copied .

The HTML defines a {{htmlelement("p")}} element for the source text to be copied, {{htmlelement("button")}} elements to copy and paste the text, and an element into which the text will be copied.

pepelsbey · 2026-10-03T11:33:38Z

+
+document.querySelector("#paste_text").addEventListener("click", async () => {
+  try {
+    // Read the text from the clipboard write it to #target_text


Suggested change

// Read the text from the clipboard write it to #target_text

// Read the text from the clipboard and write it to #target_text

pepelsbey · 2026-10-03T11:34:51Z

+As in the previous example, we create event handlers to copy the source element and paste to the target element.
+
+The code that is run to copy the data is shown below.
+Note how the code constructs the `ClipboardItem()` constructor with two representations of the same source data.


Suggested change

Note how the code constructs the `ClipboardItem()` constructor with two representations of the same source data.

Note how the code calls the `ClipboardItem()` constructor with two representations of the same source data.

“Constructs the constructor” is a bit awkward

pepelsbey · 2026-10-03T11:35:24Z

+
+### Reading and writing custom formats
+
+This example demonstrates how applications can use custom formats to copy and paste a faithful representation of their data when the format is understood, and provide a graceful fall back where it is not.


Suggested change

This example demonstrates how applications can use custom formats to copy and paste a faithful representation of their data when the format is understood, and provide a graceful fall back where it is not.

This example demonstrates how applications can use custom formats to copy and paste a faithful representation of their data when the format is understood, and provide a graceful fallback where it is not.

FF156 ClipBoard Async API - clarify types

82dbdf1

hamishwillee requested a review from a team as a code owner September 11, 2026 07:07

hamishwillee requested review from sideshowbarker and removed request for a team September 11, 2026 07:07

github-actions Bot added Content:WebAPI Web API docs size/m [PR only] 51-500 LoC changed labels Sep 11, 2026

hamishwillee mentioned this pull request Sep 11, 2026

[WebAPI] Implement Async Clipboard API web custom format support on Android #45430

Open

7 of 8 tasks

pepelsbey requested review from pepelsbey and removed request for sideshowbarker September 11, 2026 14:40

pepelsbey reviewed Sep 11, 2026

View reviewed changes

Comment thread files/en-us/web/api/clipboard/index.md Outdated

Comment thread files/en-us/web/api/clipboard/index.md Outdated

Comment thread files/en-us/web/api/clipboarditem/clipboarditem/index.md Outdated

Comment thread files/en-us/web/api/clipboarditem/clipboarditem/index.md Outdated

pepelsbey requested a review from Josh-Cena September 11, 2026 15:16

Josh-Cena removed their request for review September 11, 2026 21:49

hamishwillee and others added 3 commits September 14, 2026 10:32

review and tidy fixes

eaca1e4

Apply suggestion from @pepelsbey

ec3402e

Co-authored-by: Vadim Makeev <hi@pepelsbey.dev>

Apply suggestion from @hamishwillee

3f6865f

github-actions Bot reviewed Sep 14, 2026

View reviewed changes

Comment thread files/en-us/web/api/clipboarditem/clipboarditem/index.md Outdated

Update files/en-us/web/api/clipboarditem/clipboarditem/index.md

1a2d0ab

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

pepelsbey reviewed Sep 14, 2026

View reviewed changes

Comment thread files/en-us/web/api/clipboard/read/index.md Outdated

Comment thread files/en-us/web/api/clipboard/read/index.md Outdated

Comment thread files/en-us/web/api/clipboard/read/index.md Outdated

Comment thread files/en-us/web/api/clipboarditem/clipboarditem/index.md Outdated

hamishwillee commented Sep 15, 2026

View reviewed changes

Comment thread files/en-us/web/api/clipboard/read/index.md Outdated

hamishwillee and others added 3 commits September 15, 2026 11:20

Apply batched suggestions from code review

98f1151

Co-authored-by: Vadim Makeev <hi@pepelsbey.dev> Co-authored-by: Hamish Willee <hamishwillee@gmail.com>

Add custom format examples

a12823c

Claude driven pr review fixes

3043688

hamishwillee requested a review from pepelsbey September 15, 2026 08:36

hamishwillee changed the title ~~FF156 ClipBoard Async API - clarify types~~ FF156 ClipBoard Async API - custom types Sep 15, 2026

github-actions Bot added size/xl [PR only] >1000 LoC changed and removed size/m [PR only] 51-500 LoC changed labels Sep 15, 2026

pepelsbey requested changes Oct 3, 2026

View reviewed changes

	An app that recognizes its own custom format can paste it with data loss for users who copy from it, while other apps still receive whichever standard representations you also provide.
	An app that recognizes its own custom format can paste it without data loss for users who copy from it, while other apps still receive whichever standard representations you also provide.

		There is nothing special about the blob for the custom format: the only difference is the`web` prefix used for its key.
		The `text/html` blob omits the `SKU` column stored in the custom format, and acts as a fall back when the content is pasted in apps and browsers that don't allow the format.


		#### HTML

		The HTML defines a {{htmlelement("p")}} element for the source text to be copied, {{htmlelement("button")}} elements to copy and paste the text, and an element into which the the text will be copied .

	// Read the text from the clipboard write it to #target_text
	// Read the text from the clipboard and write it to #target_text

	Note how the code constructs the `ClipboardItem()` constructor with two representations of the same source data.
	Note how the code calls the `ClipboardItem()` constructor with two representations of the same source data.


		### Reading and writing custom formats

		This example demonstrates how applications can use custom formats to copy and paste a faithful representation of their data when the format is understood, and provide a graceful fall back where it is not.

Conversation

hamishwillee commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Sep 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

pepelsbey left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Josh-Cena commented Sep 11, 2026

Uh oh!

Uh oh!

hamishwillee commented Sep 14, 2026

Uh oh!

pepelsbey left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hamishwillee commented Sep 15, 2026

Uh oh!

hamishwillee commented Sep 20, 2026

Uh oh!

pepelsbey left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pepelsbey Oct 3, 2026

Choose a reason for hiding this comment

Uh oh!

pepelsbey Oct 3, 2026

Choose a reason for hiding this comment

Uh oh!

pepelsbey Oct 3, 2026

Choose a reason for hiding this comment

Uh oh!

pepelsbey Oct 3, 2026

Choose a reason for hiding this comment

Uh oh!

pepelsbey Oct 3, 2026

Choose a reason for hiding this comment

Uh oh!

pepelsbey Oct 3, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

hamishwillee commented Sep 11, 2026 •

edited

Loading

github-actions Bot commented Sep 11, 2026 •

edited

Loading

pepelsbey left a comment •

edited

Loading