Contribute to this guide

guideIntroduction to conversion

# What is the conversion?

The editing engine of CKEditor 5 works on two separate layers – model and view. The process of transforming one into the other is called conversion.

# Upcast conversion

When you load data into the editor, the view is created out of the markup. Then, with the help of the upcast converters, the model is created. Once that is done, the model becomes the editor state. The whole process is called upcast conversion.

A diagram explaining loading data into the editor.

# Downcast conversion

All changes, such as typing or pasting from the clipboard, are applied directly to the model. To update the editing view, e.i. the layer being displayed to the user, the engine transforms these changes in the model to the view. The same process is executed when data needs to be generated (for example, when you copy editor content or use editor.getData()). These processes are called editing and downcast conversions.

Diagram explaining interaction between the user, model, and editor output.

You can think about upcast and downcast as processes working in opposite directions, ones that are symmetrical to each other.

# Further reading

In the following guides, you will learn how to create the right converter for each case when creating your CKEditor 5 plugin.

  • Model to view (downcast)

    The model has to be transformed into the view. Learn how to achieve that by creating downcast converters.

  • View to model (upcast)

    Raw data coming into the editor has to be transformed into the model. Learn how to achieve that by creating upcast converters.

  • Conversion helpers

    There are plenty of ways to transform data between model and view. To help you do this as efficiently as possible, we provided many functions that speed up this process. This chapter will help you choose the right helper for the job.