CKEditor 4 WYSIWYG Editor Vue Integration

CKEditor 4 offers a native Vue integration through the CKEditor 4 Vue component. It provides deep integration of CKEditor 4 and Vue that lets you use the native features of the WYSIWYG editor inside a Vue component. The CKEditor 4 Vue component is compatible with Vue.js 2.x.

# Basic Usage

In order to create an editor instance in Vue, install the ckeditor4-vue npm package as a dependency of your project:

npm install ckeditor4-vue

Now you need to enable the CKEditor 4 Vue component in your application. There are two ways to do so:

• via a direct script include,
• by using ES6 module imports.

# 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:

<script src="../node_modules/ckeditor4/ckeditor.js"></script>
<script src="../node_modules/ckeditor4-vue/dist/ckeditor.js"></script>

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

Vue.use( CKEditor );

Use the <ckeditor> component in your template:

• The v-model directive enables an out–of–the–box two–way data binding.
• The config directive helps you pass the editor configuration to the editor instance.

<div id="app">
    <ckeditor v-model="editorData" :config="editorConfig"></ckeditor>
</div>

const app = new Vue( {
    el: '#app',
    data: {
        editorData: '<p>Content of the editor.</p>',
        editorConfig: {
            // The configuration of the editor.
        }
    }
} );

Voilà! You should see CKEditor 4 running in your Vue.js application.

# 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:

import Vue from 'vue';
import CKEditor from 'ckeditor4-vue';

Vue.use( CKEditor );

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

• The v-model directive enables an out–of–the–box two–way data binding.
• The config directive helps you pass the editor configuration to the editor instance.

<template>
    <div id="app">
        <ckeditor v-model="editorData" :config="editorConfig"></ckeditor>
    </div>
</template>

<script>
    export default {
        name: 'app',
        data() {
            return {
                editorData: '<p>Content of the editor.</p>',
                editorConfig: {
                    // The configuration of the editor.
                }
            };
        }
    }
</script>

# Using the component locally

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

<template>
    <div id="app">
        <ckeditor v-model="editorData" :config="editorConfig"></ckeditor>
    </div>
</template>

<script>
    export default {
        name: 'app',
        components: {
            // Use the <ckeditor> component in this view.
            ckeditor: CKEditor.component
        },
        data() {
            return {
                editorData: '<p>Content of the editor.</p>',
                editorConfig: {
                    // The configuration of the editor.
                }
            };
        }
    }
</script>

# Component Directives

# editor-url

By default, the CKEditor 4 Vue component loads the standard-all preset of the latest CKEditor 4 release from the CDN when creating the first editor. This behavior can be altered by changing the value of the editor-url directive to point to the desired CKEditor 4 script location:

<template>
    <div id="app">
        <ckeditor :editor-url="editorUrl"></ckeditor>
    </div>
</template>

<script>
    export default {
        name: 'app',
        data() {
            return {
                editorUrl: "https://your-website.example/ckeditor/ckeditor.js"
            };
        }
    }
</script>

Alternatively, you can load CKEditor before loading the CKEditor 4 Vue component. In this case the component will use the already loaded CKEditor:

<script src="custom-ckeditor.js"></script>
<script src="../node_modules/ckeditor4/ckeditor.js"></script>
<script src="../node_modules/ckeditor4-vue/dist/ckeditor.js"></script>

# type

By default, the CKEditor 4 Vue component creates a classic editor. To create an inline editor, add the type directive with the value of inline to the component tag:

<ckeditor type="inline"></ckeditor>

Every other value of the type directive will be treated as classic.

# config

Custom configuration can be passed to the editor with the config directive of the CKEditor 4 Vue component. The following example shows how to change the contents of the toolbar:

<template>
    <div id="app">
        <ckeditor :config="editorConfig"></ckeditor>
    </div>
</template>

<script>
    export default {
        name: 'app',
        data() {
            return {
                editorConfig: {
                    toolbar: [ [ 'Bold' ] ]
                }
            };
        }
    }
</script>

All configuration options can be changed this way.

# tag-name

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

<ckeditor tag-name="textarea"></ckeditor>

# 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.

<ckeditor value="<p>Content of the editor</p>"></ckeditor>

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

# 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.

<template>
    <div id="app">
        <ckeditor v-model="editorData"></ckeditor>
        <button v-on:click="emptyEditor()">Empty the editor</button>

        <h2>Editor data</h2>
        <code>{{ editorData }}</code>
    </div>
</template>

<script>
    export default {
        name: 'app',
        data() {
            return {
                editorData: '<p>Content of the editor.</p>'
            };
        },
        methods: {
            emptyEditor() {
                this.editorData = '';
            }
        }
    }
</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.

# read-only

This directive controls the readOnly property of the editor. It sets the initial read–only state of the editor and changes it during its lifecycle.

<ckeditor read-only="true"></ckeditor>

Note that you can still pass readOnly property as a config directive, however, the read-only directive will take precedence over the configuration property if set.

# throttle

Controls the minimal interval (in miliseconds) at which an input component event can be executed repeatedly as a response to the editor content changes. Higher throttle levels should ensure better editor responsiveness at the cost of slower 2-way binding synchronization.

Use this option when you expect that the editor users will work with more complicated, bigger documents to improve typing experience.

<ckeditor throttle="120"></ckeditor> // `input` event will not be fired more often than every 120 ms.

# Component events

# namespaceloaded

Fired once CKEDITOR namespace is loaded on the page. This event is called only one time for each editor instance and only when CKEDITOR 4 URL provided in editor-url directive is valid. Allows to modify global editor namespace.

<template>
    <div id="app">
        <ckeditor @namespaceloaded="onNamespaceLoaded" :config="editorConfig"></ckeditor>
    </div>
</template>

<script>
    export default {
        name: 'app',
        data() {
            return {
                editorConfig: {
                    extraPlugins: 'placeholder'
                }
            }
        },
        methods: {
            onNamespaceLoaded( CKEDITOR ) {
                // Add external `placeholder` plugin which will be available for each
                // editor instance on the page.
                CKEDITOR.plugins.addExternal( 'placeholder', '/path/to/the/placeholder/plugin', 'plugin.js' );
            }
        }
    }
</script>

# ready

Corresponds to the instanceReady editor event.

<ckeditor @ready="onEditorReady"></ckeditor>

# focus

Corresponds to the focus editor event.

<ckeditor @focus="onEditorFocus"></ckeditor>

# blur

Corresponds to the blur editor event.

<ckeditor @blur="onEditorBlur"></ckeditor>

# input

Corresponds to the change editor event. Called only once the editor’s data changed. Note that the change event requires the Undo plugin to work. Otherwise it will be called only one time on the editor initialization. See also the v-model directive to learn more.

<ckeditor @input="onEditorInput"></ckeditor>

# Editor Instance

In most cases there is no need to break the encapsulation provided by the CKEditor 4 Vue component as the editor configuration and event handlers can be configured with the component’s directives. However, if you need access to the editor object, you can use the editor property of the component’s instance:

component.instance.getData();

Please note that this property is initialised asynchronously, after mounting the component.

# CKEditor 4 Vue Integration Demo

See the working “CKEditor 4 Vue Integration” sample that showcases the most important features of the integration, including choosing the editor type, configuration and events, or setting up two-way data binding.