Rich text editor component for Vue.js

npm version

CKEditor 5 consists of ready-to-use editor builds and CKEditor 5 Framework upon which the builds are based.

The easiest way to use CKEditor 5 in your Vue.js application is by choosing one of the rich text editor builds and simply passing it to the configuration of the Vue.js component. Read more about this solution in the Quick start section.

Additionally, you can integrate CKEditor 5 from source which is a much more flexible and powerful solution, but requires some additional configuration.

The component is compatible with Vue.js 2.x.

Quick start

Install the CKEditor 5 WYSIWYG editor component for Vue.js and the editor build of your choice.

Assuming that you picked @ckeditor/ckeditor5-build-classic:

  1. npm install --save @ckeditor/ckeditor5-vue @ckeditor/ckeditor5-build-classic

You now need to enable the CKEditor component in your application. There are 2 ways to do so:

Direct script include

This is the quickest way to start using CKEditor in your project. Assuming Vue is installed, include the <script> tags for the WYSIWYG editor component and the build:

  1. <script src="../node_modules/@ckeditor/ckeditor5-build-classic/build/ckeditor.js"></script>
  2. <script src="../node_modules/@ckeditor/ckeditor5-vue/dist/ckeditor.js"></script>

Enable the component in your application by using the Vue.use() method:

  1. Vue.use( CKEditor );

Instead of calling Vue.use(), you can always use the component locally.

Use the <ckeditor> component in your template:

  • The editor directive specifies the editor build.
  • The v-model directive enables an out–of–the–box two–way data binding.
  • The config directive helps you pass the configuration to the editor instance.
  1. <div id="app">
  2.     <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
  3. </div>
  1. const app = new Vue( {
  2.     el: '#app',
  3.     data: {
  4.         editor: ClassicEditor,
  5.         editorData: '<p>Content of the editor.</p>',
  6.         editorConfig: {
  7.             // The configuration of the editor.
  8.         }
  9.     }
  10. } );

Voilà! You should see CKEditor 5 running in your Vue.js app.

See the list of supported directives and events that will help you configure the component.

Using ES6 modules

The editor component comes as a UMD module, which makes it possible to use in various environments, for instance, applications generated by Vue CLI 3, built using webpack, etc.

To create an editor instance, you must first import the editor build and the component modules into the root file of your application (e.g. main.js when generated by Vue CLI). Then, enable the component using the Vue.use() method:

  1. import Vue from 'vue';
  2. import CKEditor from '@ckeditor/ckeditor5-vue';
  4. Vue.use( CKEditor );

Instead of calling Vue.use(), you can always use the component locally.

The following example showcases a single–file component of the application. Use the <ckeditor> component in your template:

  • The editor directive specifies the editor build (the editor constructor).
  • The v-model directive enables an out–of–the–box two–way data binding.
  • The config directive helps you pass the configuration to the editor instance.
  1. <template>
  2.     <div id="app">
  3.         <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
  4.     </div>
  5. </template>
  7. <script>
  8.     import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
  10.     export default {
  11.         name: 'app',
  12.         data() {
  13.             return {
  14.                 editor: ClassicEditor,
  15.                 editorData: '<p>Content of the editor.</p>',
  16.                 editorConfig: {
  17.                     // The configuration of the editor.
  18.                 }
  19.             };
  20.         }
  21.     }
  22. </script>

See the list of supported directives and events that will help you configure the component.

Using component locally

If you do not want the CKEditor component to be enabled globally, you can skip the Vue.use( CKEditor ) part entirely. Instead, configure it in the components property of your view.

Make sure CKEditor and ClassicEditor are accessible depending on the integration scenario: as direct script includes or ES6 module imports.

  1. <template>
  2.     <div id="app">
  3.         <ckeditor :editor="editor" ... ></ckeditor>
  4.     </div>
  5. </template>
  7. <script>
  8.     export default {
  9.         name: 'app',
  10.         components: {
  11.             // Use the <ckeditor> component in this view.
  12.             ckeditor: CKEditor.component
  13.         },
  14.         data() {
  15.             return {
  16.                 editor: ClassicEditor,
  18.                 // ...
  19.             };
  20.         }
  21.     }
  22. </script>

Using CKEditor from source

Integrating the rich text editor from source allows you to use the full power of CKEditor 5 Framework.

This guide assumes that you are using Vue CLI 3+ as your boilerplate and your application has been created using the vue create command.

Learn more about building CKEditor from source in the Advanced setup guide.

Configuring vue.config.js

To build CKEditor with your application, certain changes must be made to the default project configuration.

First, install the necessary dependencies:

  1. npm install --save \
  2.     @ckeditor/ckeditor5-vue \
  3.     @ckeditor/ckeditor5-dev-webpack-plugin \
  4.     @ckeditor/ckeditor5-dev-utils \
  5.     postcss-loader \
  6.     raw-loader@0.5.1

Edit the vue.config.js file and use the following configuration. If the file is not present, create it in the root of the application (i.e. next to package.json):

  1. const path = require( 'path' );
  2. const CKEditorWebpackPlugin = require( '@ckeditor/ckeditor5-dev-webpack-plugin' );
  3. const { styles } = require( '@ckeditor/ckeditor5-dev-utils' );
  5. module.exports = {
  6.     // The source of CKEditor is encapsulated in ES6 modules. By default, the code
  7.     // from the node_modules directory is not transpiled, so you must explicitly tell
  8.     // the CLI tools to transpile JavaScript files in all ckeditor5-* modules.
  9.     transpileDependencies: [
  10.         /ckeditor5-[^/\\]+[/\\]src[/\\].+\.js$/,
  11.     ],
  13.     configureWebpack: {
  14.         plugins: [
  15.             // CKEditor needs its own plugin to be built using webpack.
  16.             new CKEditorWebpackPlugin( {
  17.                 // See https://ckeditor.com/docs/ckeditor5/latest/features/ui-language.html
  18.                 language: 'en'
  19.             } )
  20.         ]
  21.     },
  23.     // Vue CLI would normally use its own loader to load .svg and .css files, however:
  24.     //    1. The icons used by CKEditor must be loaded using raw-loader,
  25.     //    2. The CSS used by CKEditor must be transpiled using PostCSS to load properly.
  26.     chainWebpack: config => {
  27.         // (1.) To handle editor icons, get the default rule for *.svg files first:
  28.         const svgRule = config.module.rule( 'svg' );
  30.         // Then you can either:
  31.         //
  32.         // * clear all loaders for existing 'svg' rule:
  33.         //
  34.         //        svgRule.uses.clear();
  35.         //
  36.         // * or exclude ckeditor directory from node_modules:
  37.         svgRule.exclude.add( path.join( __dirname, 'node_modules', '@ckeditor' ) );
  39.         // Add an entry for *.svg files belonging to CKEditor. You can either:
  40.         //
  41.         // * modify the existing 'svg' rule:
  42.         //
  43.         //        svgRule.use( 'raw-loader' ).loader( 'raw-loader' );
  44.         //
  45.         // * or add a new one:
  46.         config.module
  47.             .rule( 'cke-svg' )
  48.             .test( /ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/ )
  49.             .use( 'raw-loader' )
  50.             .loader( 'raw-loader' );
  52.         // (2.) Transpile the .css files imported by the editor using PostCSS.
  53.         // Make sure only the CSS belonging to ckeditor5-* packages is processed this way.
  54.         config.module
  55.             .rule( 'cke-css' )
  56.             .test( /ckeditor5-[^/\\]+[/\\].+\.css$/ )
  57.             .use( 'postcss-loader' )
  58.             .loader( 'postcss-loader' )
  59.             .tap( () => {
  60.                 return styles.getPostCssConfig( {
  61.                     themeImporter: {
  62.                         themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' ),
  63.                     },
  64.                     minify: true
  65.                 } );
  66.             } );
  67.     }
  68. };

By default, the Vue CLI uses file-loader for all SVG files. The file-loader copies the file to the output directory and resolves imports into URLs. The CKEditor’s UI components use SVG source directly so the theme icons must be loaded using raw-loader. If your project uses different approach then CKEditor’s UI library you must create different webpack loader rules for your project SVG files and CKEditor’s ones.

Using the editor from source

Having configured vue.config.js, you can choose the building blocks of your editor. Install the packages necessary for your integration:

  1. npm install --save \
  2.     @ckeditor/ckeditor5-editor-classic \
  3.     @ckeditor/ckeditor5-essentials \
  4.     @ckeditor/ckeditor5-basic-styles \
  5.     @ckeditor/ckeditor5-link \
  6.     @ckeditor/ckeditor5-paragraph \
  7.     @ckeditor/ckeditor5-theme-lark

You can use more packages, depending on which features are needed in your application.

  1. import CKEditor from '@ckeditor/ckeditor5-vue';
  3. Vue.use( CKEditor );

Instead of calling Vue.use(), you can always use the component locally.

Now all you need to do is specify the list of rich text editor options (including plugins) in the editorConfig data property:

  1. <template>
  2.     <div id="app">
  3.         <ckeditor :editor="editor" v-model="editorData" :config="editorConfig"></ckeditor>
  4.     </div>
  5. </template>
  7. <script>
  8.     // ⚠️ NOTE: We don't use @ckeditor/ckeditor5-build-classic any more!
  9.     // Since we're building CKEditor from source, we use the source version of ClassicEditor.
  10.     import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
  12.     import EssentialsPlugin from '@ckeditor/ckeditor5-essentials/src/essentials';
  13.     import BoldPlugin from '@ckeditor/ckeditor5-basic-styles/src/bold';
  14.     import ItalicPlugin from '@ckeditor/ckeditor5-basic-styles/src/italic';
  15.     import LinkPlugin from '@ckeditor/ckeditor5-link/src/link';
  16.     import ParagraphPlugin from '@ckeditor/ckeditor5-paragraph/src/paragraph';
  18.     export default {
  19.         name: 'app',
  20.         data() {
  21.             return {
  22.                 editor: ClassicEditor,
  23.                 editorData: '<p>Content of the editor.</p>',
  24.                 editorConfig: {
  25.                     plugins: [
  26.                         EssentialsPlugin,
  27.                         BoldPlugin,
  28.                         ItalicPlugin,
  29.                         LinkPlugin,
  30.                         ParagraphPlugin
  31.                     ],
  33.                     toolbar: {
  34.                         items: [
  35.                             'bold',
  36.                             'italic',
  37.                             'link',
  38.                             'undo',
  39.                             'redo'
  40.                         ]
  41.                     }
  42.                 }
  43.             };
  44.         }
  45.     };
  46. </script>

Using the Document editor build

If you use the Document editor in your application, you need to manually add the editor toolbar to the DOM.

Since accessing the editor toolbar is not possible until after the editor instance is ready, put your toolbar insertion code in a method executed upon the ready event of the component, like in the following example:

  1. <template>
  2.         <div id="app">
  3.             <ckeditor :editor="editor" @ready="onReady" ... ></ckeditor>
  4.         </div>
  5. </template>
  7. <script>
  8.     import DecoupledEditor from '@ckeditor/ckeditor5-build-decoupled-document';
  10.     export default {
  11.         name: 'app',
  12.         data() {
  13.             return {
  14.                 editor: DecoupledEditor,
  16.                 // ...
  17.             };
  18.         },
  19.         methods: {
  20.             onReady( editor )  {
  21.                 // Insert the toolbar before the editable area.
  22.                 editor.ui.getEditableElement().parentElement.insertBefore(
  23.                     editor.ui.view.toolbar.element,
  24.                     editor.ui.getEditableElement()
  25.                 );
  26.             }
  27.         }
  28.     }
  29. </script>

Component directives

editor

This directive specifies the editor to be used by the component. It must directly reference the editor constructor to be used in the template.

  1. <template>
  2.         <div id="app">
  3.             <ckeditor :editor="editor" ... ></ckeditor>
  4.         </div>
  5. </template>
  7. <script>
  8.     import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
  10.     export default {
  11.         name: 'app',
  12.         data() {
  13.             return {
  14.                 editor: ClassicEditor,
  16.                 // ...
  17.             };
  18.         }
  19.     }
  20. </script>

To use more than one rich text editor build in your application, you will need to configure it from source or use a “super build”.

tag-name

By default, the editor component creates a <div> container which is used as an element passed to the editor (e.g. ClassicEditor#element). The element can be configured, so for example to create a <textarea>, use the following directive:

  1. <ckeditor :editor="editor" tag-name="textarea"></ckeditor>

v-model

A standard directive for form inputs in Vue. Unlike value, it creates a two–way data binding, which:

  • sets the initial editor content,
  • automatically updates the state of the application as the editor content changes (e.g. as the user types),
  • can be used to set the editor content when necessary.
  1. <template>
  2.     <div id="app">
  3.         <ckeditor :editor="editor" v-model="editorData"></ckeditor>
  4.         <button v-on:click="emptyEditor()">Empty the editor</button>
  6.         <h2>Editor data</h2>
  7.         <code>{{ editorData }}</code>
  8.     </div>
  9. </template>
  11. <script>
  12.     import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
  14.     export default {
  15.         name: 'app',
  16.         data() {
  17.             return {
  18.                 editor: ClassicEditor,
  19.                 editorData: '<p>Content of the editor.</p>'
  20.             };
  21.         },
  22.         methods: {
  23.             emptyEditor() {
  24.                 this.editorData = '';
  25.             }
  26.         }
  27.     }
  28. </script>

In the above example, the editorData property will be updated automatically as the user types and changes the content. It can also be used to change (as in emptyEditor()) or set the initial content of the editor.

If you only want to execute an action when the editor data changes, use the input event.

value

Allows a one–way data binding that sets the content of the editor. Unlike v-model, the value will not be updated when the content of the editor changes.

  1. <template>
  2.     <div id="app">
  3.         <ckeditor :editor="editor" :value="editorData"></ckeditor>
  4.     </div>
  5. </template>
  7. <script>
  8.     import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
  10.     export default {
  11.         name: 'app',
  12.         data() {
  13.             return {
  14.                 editor: ClassicEditor,
  15.                 editorData: '<p>Content of the editor.</p>'
  16.             };
  17.         }
  18.     }
  19. </script>

To execute an action when the editor data changes, use the input event.

config

Specifies the configuration of the editor.

  1. <template>
  2.     <div id="app">
  3.         <ckeditor :editor="editor" :config="editorConfig"></ckeditor>
  4.     </div>
  5. </template>
  7. <script>
  8.     import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
  10.     export default {
  11.         name: 'app',
  12.         data() {
  13.             return {
  14.                 editor: ClassicEditor,
  15.                 editorConfig: {
  16.                     toolbar: [ 'bold', 'italic', '|', 'link' ]
  17.                 }
  18.             };
  19.         }
  20.     }
  21. </script>

disabled

This directive controls the isReadOnly property of the editor.

It sets the initial read–only state of the editor and changes it during its lifecycle.

  1. <template>
  2.     <div id="app">
  3.         <ckeditor :editor="editor" :disabled="editorDisabled"></ckeditor>
  4.     </div>
  5. </template>
  7. <script>
  8.     import ClassicEditor from '@ckeditor/ckeditor5-build-classic';
  10.     export default {
  11.         name: 'app',
  12.         data() {
  13.             return {
  14.                 editor: ClassicEditor,
  15.                 // This editor will be read–only when created.
  16.                 editorDisabled: true
  17.             };
  18.         }
  19.     }
  20. </script>

Component events

ready

Corresponds to the ready editor event.

  1. <ckeditor :editor="editor" @ready="onEditorReady"></ckeditor>

focus

Corresponds to the focus editor event.

  1. <ckeditor :editor="editor" @focus="onEditorFocus"></ckeditor>

blur

Corresponds to the blur editor event.

  1. <ckeditor :editor="editor" @blur="onEditorBlur"></ckeditor>

input

Corresponds to the change:data editor event. See the v-model directive to learn more.

  1. <ckeditor :editor="editor" @input="onEditorInput"></ckeditor>

destroy

Corresponds to the destroy editor event.

Note: Because the destruction of the editor is promise–driven, this event can be fired before the actual promise resolves.

  1. <ckeditor :editor="editor" @destroy="onEditorDestroy"></ckeditor>

Contributing and reporting issues

The source code of this component is available on GitHub in https://github.com/ckeditor/ckeditor5-vue.