Clipboard API
Limited availability
This feature is not Baseline because it does not work in some of the most widely-used browsers.
TheClipboard APIprovides the ability to respond to clipboard commands (cut, copy, and paste), as well as to asynchronously read from and write to the system clipboard.
Note:Use this API in preference to the deprecateddocument.execCommand()
method for accessing the clipboard.
Note:This API isnot availableinWeb Workers(not exposed viaWorkerNavigator
).
Concepts and usage
Thesystem clipboardis a data buffer belonging to the operating system hosting the browser, which is used for short-term data storage and/or data transfers between documents or applications. It is usually implemented as an anonymous, temporarydata buffer,sometimes called thepaste buffer,that can be accessed from most or all programs within the environment via defined programming interfaces.
The Clipboard API allows users to programmatically read and write text and other kinds of data to and from the system clipboard insecure contexts,provided the user has met the criteria outlined in theSecurity considerations.
Events are fired as the result ofcut
,copy
,andpaste
operations modifying the clipboard.
The events have a default action, for example thecopy
action copies the current selection to the system clipboard by default.
The default action can be overriden by the event handler — see each of the events for more information.
Interfaces
Clipboard
Secure context-
Provides an interface for reading and writing text and data to or from the system clipboard. The specification refers to this as the 'Async Clipboard API'.
ClipboardEvent
-
Represents events providing information related to modification of the clipboard, that is
cut
,copy
,andpaste
events. The specification refers to this as the 'Clipboard Event API'. ClipboardItem
Secure context-
Represents a single item format, used when reading or writing data.
Extensions to other interfaces
The Clipboard API extends the following APIs, adding the listed features.
-
Returns a
Clipboard
object that provides read and write access to the system clipboard. Element: copy
event-
An event fired whenever the user initiates a copy action.
Element: cut
event-
An event fired whenever the user initiates a cut action.
Element: paste
event-
An event fired whenever the user initiates a paste action.
Security considerations
The Clipboard API allows users to programmatically read and write text and other kinds of data to and from the system clipboard insecure contexts.
The specification requires that a user has recently interacted with the page in order to read from the clipboard (transient user activationis required).
If the read operation is caused by user interaction with a browser or OS "paste element" (such as a context menu), the browser is expected to prompt the user for acknowledgement.
For writing to the clipboard the specification expects that the page has been granted thePermissions APIclipboard-write
permission, and the browser may also requiretransient user activation.
Browsers may place additional restrictions over use of the methods to access the clipboard.
Browser implementations have diverged from the specification. The differences are captured in theBrowser compatibilitysection and the current state is summarized below:
Chromium browsers:
-
Reading requires thePermissions API
clipboard-read
permission be granted. Transient activation is not required. -
Writing requires either the
clipboard-read
permission or transient activation. If the permission is granted, it persists, and further transient activation is not required. - The HTTPPermissions-Policypermissions
clipboard-read
andclipboard-write
must be allowed for<iframe>
elements that access the clipboard. - No persistent paste-prompt is displayed when a read operation is caused by a browser or OS "paste element".
Firefox & Safari:
- Reading and writing require transient activation.
- The paste-prompt is suppressed if reading same-origin clipboard content, but not cross-origin content.
- The
clipboard-read
andclipboard-write
permissions are not supported (and not planned to be supported) by Firefox or Safari.
FirefoxWeb Extensions:
-
Reading text is only available for extensions with the Web Extension
clipboardRead
permission. With this permission the extension does not require transient activation or a paste prompt. -
Writing text is available in secure context and with transient activation.
With the Web Extension
clipboardWrite
permission transient activation is not required.
Examples
Accessing the clipboard
The system clipboard is accessed through theNavigator.clipboard
global.
This snippet fetches the text from the clipboard and appends it to the first element found with the classeditor
.
SincereadText()
(andread()
,for that matter) returns an empty string if the clipboard isn't text, this code is safe.
navigator.clipboard
.readText()
.then(
(clipText)=>(document.querySelector(".editor").innerText+=clipText),
);
Specifications
Specification |
---|
Clipboard API and events #clipboard-interface |
Clipboard API and events #clipboard-event-interfaces |
Clipboard API and events #clipboarditem |
Browser compatibility
api.Clipboard
BCD tables only load in the browser
api.ClipboardEvent
BCD tables only load in the browser
api.ClipboardItem
BCD tables only load in the browser