# Clipboard

The clipboard feature (implemented by the [`Clipboard`](../../api/module_clipboard_clipboard-Clipboard.md) plugin) is responsible for the integration with the native clipboard. The native clipboard is a feature of the operating system and the browser. It is used when the user copies, cuts, pastes, or drags and drops content within the editor or from/to the “outside.”

CKEditor 5 intercepts all native events like `copy`, `cut`, or `drop` and handles them on its side. The goal is to not allow the browser to touch the content in the rich text editor. This could lead to the browser messing it up.

There are two directions of content processing:

* When the content is being pasted or dropped into the editor, it goes through the [input pipeline](#input-pipeline).
* When the content is being copied, cut, or dragged from the editor, it goes through the [output pipeline](#output-pipeline).

Both pipelines allow the features to process the content to be inserted or set to the clipboard. They also allow to override the default mechanisms at different stages of these processes.

<a id="input-pipeline">

## Input pipeline

When the user pastes or drops content into the editor, the browser fires an event. The clipboard feature intercepts this event and starts the following mechanism:

1. [`ClipboardObserver`](../../api/module_clipboard_clipboardobserver-ClipboardObserver.md) turns this event into a synthetic [`view.Document#paste`](../../api/module_engine_view_document-ViewDocument.md#event-paste) or [`view.Document#drop`](../../api/module_engine_view_document-ViewDocument.md#event-drop).
2. The content to be inserted by both actions (paste and drop) should usually be processed in the same way and both actions have a similar effect. Both events are thus turned into a single [`view.Document#clipboardInput`](../../api/module_engine_view_document-ViewDocument.md#event-clipboardInput) event for easier handling.
3. Next, the clipboard feature listens to the `view.Document#clipboardInput` event and retrieves and pre-processes the `text/html` or `text/plain` content which it finds in the [event’s `dataTransfer`](../../api/module_engine_view_datatransfer-ViewDataTransfer.md). It then fires the [`ClipboardPipeline#inputTransformation`](../../api/module_clipboard_clipboardpipeline-ClipboardPipeline.md#event-inputTransformation) event with the retrieved content in the event data `content` property as a [`view.DocumentFragment`](../../api/module_engine_view_documentfragment-ViewDocumentFragment.md).
4. Then, the clipboard feature listens to the `ClipboardPipeline#inputTransformation` event. It takes the processed content and transforms it to the [`model.DocumentFragment`](../../api/module_engine_model_documentfragment-ModelDocumentFragment.md). It then fires the [`ClipboardPipeline#contentInsertion`](../../api/module_clipboard_clipboardpipeline-ClipboardPipeline.md#event-contentInsertion) event with the transformed content in the event data `content` property as a [`model.DocumentFragment`](../../api/module_engine_model_documentfragment-ModelDocumentFragment.md).
5. Finally, the clipboard feature listens to the `ClipboardPipeline#contentInsertion` event. It takes the model fragment and [inserts](../../api/module_engine_model_model-Model.md#function-insertContent) it into the editor. Then it stores the range which contains all the performed changes in the `resultRange` property of the event data.

The clipboard feature listens to the `view.Document#clipboardInput`, `ClipboardPipeline#inputTransformation`, and `ClipboardPipeline#contentInsertion` events using [low priority listeners](event-system.md#listener-priorities). This means that adding a normal listener and calling `evt.stop()` allows overriding the behavior implemented by the clipboard feature. It is a similar mechanism to the DOM’s `evt.preventDefault()` that lets you override the default browser behavior.

<a id="input-pipeline-events-overview">

### Input pipeline events overview

```
 ┌──────────────────────┐          ┌──────────────────────┐
 │     view.Document    │          │     view.Document    │
 │         paste        │          │         drop         │
 └───────────┬──────────┘          └───────────┬──────────┘
             │                                 │
             └────────────────┌────────────────┘
                              │
                    ┌─────────V────────┐
                    │   view.Document  │   Retrieves text/html from data.dataTransfer
                    │  clipboardInput  │   and processes it to view.DocumentFragment.
                    └─────────┬────────┘
                              │
                  ┌───────────V───────────┐
                  │   ClipboardPipeline   │   Converts view.DocumentFragment
                  │  inputTransformation  │   to model.DocumentFragment.
                  └───────────┬───────────┘
                              │
                   ┌──────────V──────────┐
                   │  ClipboardPipeline  │   Calls model.insertContent().
                   │   contentInsertion  │
                   └─────────────────────┘
```

<a id="handling-clipboard-input-differently">

### Handling clipboard input differently

By default, the clipboard feature retrieves `text/html` or `text/plain` from the clipboard. It normalizes the data a bit (for example, cleans up the [mess with whitespaces](https://github.com/ckeditor/ckeditor5-clipboard/issues/2)). It converts it to a [view `DocumentFragment`](../../api/module_engine_view_documentfragment-ViewDocumentFragment.md) and fires the `ClipboardPipeline#inputTransformation` event with the document fragment for further processing.

You can use the [`view.Document#clipboardInput`](../../api/module_engine_view_document-ViewDocument.md#event-clipboardInput) event to override this behavior. For example, you can use it to:

* Handle pasted or dropped files. You can retrieve these from the `dataTransfer`.

  Handling file upload requires, however, a lot more than reading [`dataTransfer.files`](../../api/module_engine_view_datatransfer-ViewDataTransfer.md#member-files). For a complete code example, check the source code of plugins like [`ImageUploadEditing`](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-image/src/imageupload/imageuploadediting.ts).

* Change the type of data that the clipboard feature reads from the clipboard. For instance, you may want to use `application/rtf` if it is present in the `dataTransfer` (and ignore `text/html` in that case).

  ```js
  editor.editing.view.document.on( 'clipboardInput', ( evt, data ) => {
  	const dataTransfer = data.dataTransfer;
  	const rtfContent = dataTransfer.getData( 'application/rtf' );

  	// If no RTF was pasted, abort and let the clipboard feature handle the input.
  	if ( !rtfContent ) {
  		return;
  	}

  	// Convert an RTF raw string to a view document fragment.
  	const viewContent = convertRtfStringToView( rtfContent );

  	// Pass the view fragment to the default clipboard input handler
  	// to allow further processing of the content.
  	data.content = viewContent;
  } );
  ```

<a id="processing-input-content">

### Processing input content

The [`ClipboardPipeline#inputTransformation`](../../api/module_clipboard_clipboardpipeline-ClipboardPipeline.md#event-inputTransformation) event lets you process the content which is going to be inserted into the editor.

The default action is to fire a [`ClipboardPipeline#contentInsertion`](../../api/module_clipboard_clipboardpipeline-ClipboardPipeline.md#event-contentInsertion) event. This event will [insert](../../api/module_engine_model_model-Model.md#function-insertContent) the content (`data.content`, represented by a [`ViewDocumentFragment`](../../api/module_engine_view_documentfragment-ViewDocumentFragment.md)) to the editor if the data is not empty.

At this stage, features can process the pasted content. For example, you can implement a feature that wants to transform the pasted text into a link in the following way:

```js
const writer = new ViewUpcastWriter( editor.editing.view.document );

editor.plugins.get( 'ClipboardPipeline' ).on( 'inputTransformation', ( evt, data ) => {
	if ( data.content.childCount == 1 && isUrlText( data.content.getChild( 0 ) ) ) {
		const linkUrl = data.content.getChild( 0 ).data;

		data.content = writer.createDocumentFragment( [
			writer.createElement(
				'a',
				{ href: linkUrl },
				[ writer.createText( linkUrl ) ]
			)
		] );
	}
} );
```

The default action (inserting the content into the editor) is performed by a low-priority listener, so it can be overridden by a normal one. With the `lowest` priority, you can also execute actions after the content has already been inserted.

```js
editor.plugins.get( 'ClipboardPipeline' ).on( 'contentInsertion', ( evt, data ) => {
	console.log( 'Content was inserted.' );
}, { priority: 'lowest' } );
```

> **Note**
>
> Check out the [event system deep dive](event-system.md#listener-priorities) guide to learn more about event listener priorities.

<a id="paste-as-plain-text-plugin-example">

### Paste as plain text plugin example

You can use the knowledge from the earlier sections to create a complete plugin. A perfect example to follow is our [`PastePlainText`](https://github.com/ckeditor/ckeditor5/blob/master/packages/ckeditor5-clipboard/src/pasteplaintext.ts) which pastes plain text when `Shift` is pressed. If you are not familiar with creating plugins in CKEditor 5, start by reading the [Creating a simple plugin](../tutorials/crash-course/editor.md) guide.

<a id="output-pipeline">

## Output pipeline

The output pipeline is the equivalent of the input pipeline but for the copy and cut operations. It allows to process the content that will be then put into the clipboard or to override the whole process.

<a id="output-pipeline-events-overview">

### Output pipeline events overview

```
 ┌──────────────────────┐          ┌──────────────────────┐   Retrieves the selected
 │     view.Document    │          │     view.Document    │   model.DocumentFragment
 │         copy         │          │          cut         │   and fires the `outputTransformation`
 └───────────┬──────────┘          └───────────┬──────────┘   event.
             │                                 │
             └────────────────┌────────────────┘
                              │
                ┌─────────────V────────────┐   Processes model.DocumentFragment
                │     ClipboardPipeline    │   and converts it to
                │    outputTransformation  │   view.DocumentFragment.
                └──────────────────────────┘
                              │
                ┌─────────────V────────────┐   Processes view.DocumentFragment
                │       view.Document      │   to text/html and text/plain
                │      clipboardOutput     │   and stores results in data.dataTransfer.
                └──────────────────────────┘
```

<a id="1-on-link-moduleengineviewdocumentviewdocumenteventcopy-viewdocumentcopy-and-link-moduleengineviewdocumentviewdocumenteventcut-viewdocumentcut">

### 1. On [`view.Document#copy`](../../api/module_engine_view_document-ViewDocument.md#event-copy) and [`view.Document#cut`](../../api/module_engine_view_document-ViewDocument.md#event-cut)

The default action is to:

1. [Get the selected content](../../api/module_engine_model_model-Model.md#function-getSelectedContent) from the editor.
2. Prevent the default action of the native `copy` or `cut` event.
3. Fire [`clipboard.ClipboardPipeline#outputTransformation`](../../api/module_clipboard_clipboardpipeline-ClipboardPipeline.md#event-outputTransformation)\` with a selected content represented by a [model document fragment](../../api/module_engine_model_documentfragment-ModelDocumentFragment.md).

<a id="2-on-link-moduleclipboardclipboardpipelineclipboardpipelineeventoutputtransformation-clipboardclipboardpipelineoutputtransformation">

### 2. On [`clipboard.ClipboardPipeline#outputTransformation`](../../api/module_clipboard_clipboardpipeline-ClipboardPipeline.md#event-outputTransformation)

The default action is to:

1. Processes `data.content` represented by a [model document fragment](../../api/module_engine_model_documentfragment-ModelDocumentFragment.md).
2. Fire [`view.Document#clipboardOutput`](../../api/module_engine_view_document-ViewDocument.md#event-clipboardOutput) with a processed `data.content` converted to a [view document fragment](../../api/module_engine_view_documentfragment-ViewDocumentFragment.md).

<a id="3-on-link-moduleengineviewdocumentviewdocumenteventclipboardoutput-viewdocumentclipboardoutput">

### 3. On [`view.Document#clipboardOutput`](../../api/module_engine_view_document-ViewDocument.md#event-clipboardOutput)

The default action is to put the content (`data.content`, represented by a [`ViewDocumentFragment`](../../api/module_engine_view_documentfragment-ViewDocumentFragment.md)) to the clipboard as HTML. In the case of the cut operation, the selected content is also deleted from the editor.

This action is performed by a low-priority listener, so it can be overridden by a normal one.

At this stage other features can process the copied or cut content.

---

Full index of the CKEditor 5 documentation: [llms.txt](../../../llms.txt)