Clipboard API and events

W3C Working Draft 12 April 2011

This version:
Latest published version:
Previous version:
Latest editor's draft:
Hallvord R. M. Steen, Opera Software


This document describes APIs for clipboard operations such as copy, cut and paste in web applications.

Status of This Document

This section describes the status of this document at the time of its publication. Other documents may supersede this document. A list of current W3C publications and the latest revision of this technical report can be found in the W3C technical reports index at http://www.w3.org/TR/.

NOTE: feedback on any details of the spec is welcome, but particularly on the question of whether we should create a registry of clipboard data types and where such a registry should be maintained.

This document was published by the Web Applications Working Group as a Working Draft. This document is intended to become a W3C Recommendation. If you wish to make comments regarding this document, please send them to public-webapps@w3.org (subscribe, archives). All feedback is welcome.

Publication as a Working Draft does not imply endorsement by the W3C Membership. This is a draft document and may be updated, replaced or obsoleted by other documents at any time. It is inappropriate to cite this document as other than work in progress.

This document was produced by a group operating under the 5 February 2004 W3C Patent Policy. W3C maintains a public list of any patent disclosures made in connection with the deliverables of the group; that page also includes instructions for disclosing a patent. An individual who has actual knowledge of a patent which the individual believes contains Essential Claim(s) must disclose the information in accordance with section 6 of the W3C Patent Policy.

Table of Contents

1. Conformance

As well as sections marked as non-normative, all authoring guidelines, diagrams, examples, and notes in this specification are non-normative. Everything else in this specification is normative.

The key words must, must not, required, should, should not, recommended, may, and optional in this specification are to be interpreted as described in [RFC2119].

2. Introduction

This section is informative

This specification defines the common clipboard operations of cutting, copying and pasting, in such a way that they are exposed to Web Applications and can be adapted to provide advanced functionalities. Its goal is to provide for compatibility where possible with existing implementations.

3. Use Cases

This section is informative

There are many use cases for being able to change the default clipboard operations (cut/copy/paste). We have collected a few samples to demonstrate possible uses, although these may not all be supported by this specification.

Rich content editing

When copying text which contains hyperlinks or other structure, it is often useful to be able to reformat the content to preserve important information.

Graphics with built-in semantics

In order to make web applications which allow the manipulation of rich text, or of graphic content such as SVG, it is useful to provide a mechanism that allows for copying more than just the rendered content.

Mathematical information

With content such as mathematics, simply copying rendered text and pasting it into another application generally leads to most of the semantics being lost. MathML often needs to be transformed to be copied as plain text, for example to make sure "to the power of" is shown with the caret "^" sign. Also, the XML source could be placed in the clipboard with the appropriate transformation occurring when pasting.

4. Events

4.1 copy event

When the user initiates a copy operation, the implementation must fire a copy event. Its default action is to place the selected data on the clipboard.

The current selection must not be affected.

If there is no selection, the event has no default action, and the clipboard must not be modified except in response to the setData() method.

What about for example clipboardData.items.add(), or clipboardData.clearData() called from a copy event listener when there is no selection? The event has no default action, so these calls should probably successfully modify clipboard contents.


4.2 cut event

When the user initiates a cut operation, the implementation must fire a cut event. In an editable context, its default action is to place the selected data on the clipboard and remove the selection from the document.

In a non-editable context, or if there is no selection, the cut event has no default action, but the implementation must fire the event regardless.

What happens if there is a selection which is cut but the event listener also calls clipboardData.items.add()? Short answer: the default action will undo what the script has done, so the .add() will have no apparent effect - is this clear enough from current text?

The cut event must fire before the selected data is removed. When the cut operation is completed, the selection must be collapsed.


4.3 paste event

When the user initiates a paste operation, the implementation must fire a paste event. The event must fire before any clipboard data is inserted.

If the cursor is in an editable element, the default action is to insert clipboard data in the most suitable format supported for the given context.

The paste event has no default action in a non-editable context, but implementations must fire the event regardless.


5. Clipboard event interface

The ClipboardEvent interface extends the Event interface [DOMEVENTS].

A synthetic paste event must not give a script access to data on the real system clipboard. Synthetic cut and copy events must not modify data on the system clipboard.

interface ClipboardEvent : Event {
    readonly attribute DataTransfer clipboardData;
    void initClipboardEvent (in DOMString eventType, in boolean canBubble, in boolean cancelable, in DOMString dataType, in DOMString data);

5.1 Attributes

clipboardData of type DataTransfer, readonly
The clipboardData attribute is an instance of the DataTransfer interface which lets a script read and manipulate values on the system clipboard during user-initiated copy, cut and paste operations. The associated drag data store is a live but filtered view of the system clipboard, exposing all data types the implementation knows the script can safely access.
No exceptions.

5.2 Methods

This method initializes attributes of an Event created through the DocumentEvent.createEvent() method. [DOMEVENTS]. The dataType argument is a string, for example but not limited to a MIME type, which describes the format of the data. Event listeners triggered by the synthetic event can get access to the data by calling DataTransfer.getData() with a string which case-insensitively matches the dataType argument.
eventTypeDOMStringThe event type, i.e. 'cut', 'copy' or 'paste'
canBubblebooleanWhether the event bubbles
cancelablebooleanWhether the event can be cancelled
dataTypeDOMStringThe type of data the event contains
dataDOMStringThe data
No exceptions.
Return type: void
Should we allow any type for the "data" argument, rather than limiting it to DOMString?

5.3 Determining the target property for clipboard events

In an editable context, the event object's target property must refer to the element that contains the start of the selection in document order, i.e. the end that is closer to the beginning of the document. In a non-editable document, the event's target must refer to a node focused for example by clicking, using the tab key, or by an interactive cursor, or to the BODY element if no other node has focus.

6. DataTransfer interface

This section is informative. The normative specification for the DataTransfer interface is found in [HTML5]'s Drag and Drop section.

TODO: review/sync with DataTransfer. There will be a very brief informative (not normative) text below for each method, clearly indicating that the normative stuff is in the HTML5 spec. We will however maintain tests for this, so keeping in sync with HTML5 will remain important.

Issues we need addressed in HTML5
SummaryHTML5 bugBrowser ref
Calling getData() too many or too few arguments should throw11857WebKit (Chrome)
Return value of setData()/clearData() should be boolean12443IE
Can make better use of .types for copy/cut events, to indicate what types are supported by the implementation and/or system clipboard?(Suggestion, not implemented anywhere)
A way to indicate the "id" of different items so that they can be referenced from the "main" content? (e.g. images embedded in HTML - to indicate that <img src="cid:img1"> references items[1], we could define an .id property so that clipboardData.items[1].id is 'img1'?)Unknown
interface clipboardData : DataTransfer {
    attribute DataTransferItems items;
    attribute DOMStringList     types;
    DOMString getData (in DOMString type);
    boolean   setData (in DOMString type, in DOMString data);
    boolean   clearData ([Optional] in DOMString type);

6.1 Attributes

items of type DataTransferItems
When pasting multi-part or non-textual data, the items property returns a DataTransferItems list of parts. See HTML5 for details [HTML5].
No exceptions.
types of type DOMStringList
The types property returns a DOMStringList of MIME type strings [RFC2046], see HTML5 for details [HTML5].
No exceptions.

6.2 Methods


Calling clearData() empties the system clipboard, or removes the specified type of data from the clipboard. See HTML5 for details [HTML5].

typeDOMStringThe type of data to clear
No exceptions.
Return type: boolean

Calling getData() from within a paste event handler will return the clipboard data in the specified format. See HTML5 for details [HTML5].

Implementations are encouraged to support 'text/html' to retrieve any HTML formatted data on the system clipboard, but see the security section of this spec for security and privacy concerns.

typeDOMStringThe type of data to get
No exceptions.
Return type: DOMString

Calling setData() from within an copy/cut event handler modifies the data which will be placed on the clipboard, for the specified format. See HTML5 for details [HTML5]

Note: Due to limitations in the implementation of operating system clipboards, scripts should not assume that custom formats will be available to other applications on the system. For example, there is a limit to how many custom clipboard formats can be registered in Microsoft Windows. While it is possible to use any string for setData()'s type argument, sticking to common types is recommended.

Should we list some "common types"?

Calling setData() from a paste event handler must not modify the data that is inserted, and must not modify the data on the clipboard.

What about the other clipboardData.* methods when called from a paste event handler? We should refer to HTML5 and say drag data store mode is in read-only mode for paste events. Will be spec'ed this way when I have time to write corresponding tests..

If content in the document is selected, the default action of a copy event is to place the selection on the clipboard. If content is selected and the selection is in an editable context, the default action of a cut event is to place the selection on the clipboard. Hence, in those cases the script calling setData() also needs to cancel the default action of the event with event.preventDefault(). Otherwise, the data the script intends to place on the clipboard will be overwritten by the default action.

typeDOMStringThe type of data being placed on the clipboard
dataDOMStringThe data being added to the clipboard
No exceptions.
Return type: boolean

Integration with other scripts and events

Integration with rich text editing APIs

If an implementation supports the document.execCommand method and allows calling it with the commands "cut", "copy" and "paste", the implementation must fire the corresponding events. The event is syncronous and may prevent the execCommand() call from having its normal effect.

7. Interaction with other events

If the clipboard operation is triggered by keyboard input, the implementation must fire the corresponding event as the default action of the keydown event that initiates the clipboard operation. For example, if the user presses Ctrl-C to copy, dispatching a copy event must be the default action of the C key's keydown event. The event is asyncronous but must be dispatched before keyup events for the relevant keys.

The default action of the cut and paste events may cause the implementation to dispatch other supported events, such as textInput, input, change, validation events, DOMCharacterDataModified and DOMNodeRemoved / DOMNodeInserted. Any such events are queued up to fire after processing of the cut/paste event is finished.

The implementation must not dispatch other input-related events like textInput, input, change, and validation events in response to the copy operation.

7.1 Event listeners that modify selection or focus

If the event listener modifies the selection or focus, the clipboard action must be completed on the modified selection.

8. Pasting data with multiple parts

This section needs to be more specific on how different types of data should be handled. We probably need to specify different algorithms for exposing data types as "drag data store" entries, and set up some kind of registry mapping the various data types (both MIME types and platform-specific type identifiers) to various algorithms.

Security precautions


This section is informative.

There are two security risks associated with pasting formatted or multi-part data.

To determine what policies to use, the factors we consider are

Security policies

The implementation must not download referenced online resources and expose their contents in the FileList.

Should we allow this for same-origin copy/paste content? There is no strong use case for doing so, since pasting markup which references online content should "just work" in the sense that referenced content should affect the rendering without the script having direct access to it.

If the data on the clipboard is not from a local application, the implementation must not give access to any referenced local files.

If the data originates from a web site, and the origin of the web site and the origin of the document associated with the script that created the event listener differs, the implementation should apply the sanitization algorithm before exposing HTML data.

Origin of dataOrigin of scriptRules
Originates from online sourceSame as dataDo not sanitize HTML. Do not access any local files.
Different originSanitize content. Do not access any local files.
Originates from local applicationAnyDo not sanitize HTML. Grant access to local files

For example, if the data contains <img src="file://localhost/example.jpg"> but the data's origin is an online resource, the implementation must not expose the content of example.jpg as an entry in the files attribute.

Using clipboardData.files list for multi-part paste

Some formats may contain multiple parts and embed images or other forms of data. Implementations must handle data with sub-parts by populating the FileList files attribute of the DataTransfer interface. References to sub-parts must be replaced by content-id references using the cid: URL scheme [RFC2392]. The identifier of each sub-part is its index in the FileList.

For example, if the user pastes some HTML that contains one IMG tag linking to an image on the local hard drive, a compliant implementation would add a File item to the files list, and modify the SRC attribute of the IMG tag to read src="cid:0" to reference the 0th file in the filelist.

9. Security and privacy considerations

Enabling authors to change what is copied by a user, or to make an automated copy of something that was never selected and allowing unrestricted calls to paste information can raise various security and privacy concerns.

An example scenario of a problem is where a user selects a link and copies it, but a different link is copied to the clipboard. The effect of this can range from an unexpected result on pasting to an attempted "phishing" attack.

Privacy concerns

Untrusted scripts should not get uncontrolled access to a user's clipboard data. This specification assumes that granting access to the current clipboard data when a user explicitly initiates a paste operation from the UA's trusted chrome is acceptable. However, implementors must proceed carefully, and as a minimum implement the precautions below:

Implementations may choose to further limit the functionality provided by the DataTransfer interface. For example, an implementation may allow the user to disable this API, or configure which web sites should be granted access to it.

Nuisance considerations

Scripts may use the DataTransfer API to annoy and confuse users by altering the data on the system clipboard from copy and cut events. This specification does not attempt to prevent such nuisances, though implementations may add additional restrictions.

Implementations must handle scripts that try to place excessive amounts of data on the clipboard gracefully.

10. Cross-origin copy/paste of source code

How do we safeguard cross-origin copy/paste of source code? Are below rules sufficient to prevent sneaky cross-site request forgery attacks?

Pasting HTML and other markup-based content copied from one site into another site might compromise the security of the former site, for example by giving the second site access to passwords, nonces and other sensitive data that might be embedded in the markup.

If a script calls getData('text/html'), the implementation supports pasting HTML, and the data available on the clipboard is from a different origin, the implementation must sanitize the content by following these steps:

  1. Parse the code on the clipboard to a DOM tree
  2. Remove all of the following elements: SCRIPT, APPLET, OBJECT, FORM, INPUT, BUTTON, TEXTAREA, SELECT, OPTION, OPTGROUP and comment nodes. For all mentioned elements except FORM, also remove all child nodes.
  3. Remove any elements whose computed style's display property is 'none'
  4. Remove all event handler attributes from all elements
  5. Remove all data- attributes from all elements
  6. If the implementation supports embedding javascript: URLs or other forms of scripting inside CSS instructions, such scripts must be removed.
  7. Remove HTML comments.
  8. Serialize the DOM and return the generated string to the script

Implementations may let the user indicate that an app is trusted to not attack other apps and apply its own safety measures, thus bypass the above algorithm. Implementations may also implement additional restrictions, for example only support text/plain if the user does a cross-origin paste, or only support text/plain if content from an encrypted origin is pasted into a non-encrypted page.


This section is informative

The editors would like to acknowledge their intellectual debt to the documentation of Data Transfer functionalities from Microsoft [MICROSOFT-CLIP-OP] and earlier drafts of the [HTML5] specification. We are also grateful for the draft "safe copy and paste" from Paul Libbrecht.

We would like to acknowledge the contributions made by the following:

Shawn Carnell, Daniel Dardailler, Al Gilman, Lachlan Hunt, Aaron Leventhal, Jim Ley, Paul Libbrecht, "Martijn", Dave Poehlman, "ROBO Design", Janina Sajka, Rich Schwerdtfeger, Jonas Sicking, Maciej Stachowiak, Mihai Sucan, Tom Wlodkowski, Anne van Kesteren, Tarquin Wilton-Jones, Dmitry Titov, Robert O'Callahan, Ryosuke Niwa, Ian Hickson, Ojan Vafai, Daniel Cheng.

A. References

A.1 Normative references

Björn Höhrmann; Tom Pixley; Philippe Le Hégaret. Document Object Model (DOM) Level 3 Events Specification. 21 December 2007. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2007/WD-DOM-Level-3-Events-20071221
Ian Hickson; David Hyatt. HTML 5. 4 March 2010. W3C Working Draft. (Work in progress.) URL: http://www.w3.org/TR/2010/WD-html5-20100304/
N. Freed; N. Borenstein. Multipurpose Internet Mail Extensions (MIME) Part Two: Media Types. November 1996. Internet RFC 2046. URL: http://www.ietf.org/rfc/rfc2046.txt
S. Bradner. Key words for use in RFCs to Indicate Requirement Levels. March 1997. Internet RFC 2119. URL: http://www.ietf.org/rfc/rfc2119.txt
E. Levinson. Content-ID and Message-ID Uniform Resource Locators. August 1998. Internet RFC 2392. URL: http://www.ietf.org/rfc/rfc2392.txt

A.2 Informative references

Microsoft Developer Network. About DHTML Data Transfer. URL: http://msdn.microsoft.com/en-us/library/ms537658.aspx