CKEditor 4 WYSIWYG Editor Angular Integration

CKEditor 4 offers a native Angular integration through the CKEditor 4 Angular component. It provides deep integration of CKEditor 4 and Angular that lets you use the native features of the WYSIWYG editor inside an Angular component. The CKEditor 4 Angular component is compatible with Angular versions 5.0 and later.

# Basic Usage

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

npm install ckeditor4-angular

After installing, import CKEditorModule to your application:

import { CKEditorModule } from 'ckeditor4-angular';

@NgModule( {
    imports: [
        ...
        CKEditorModule,
        ...
    ],
    …
} )

You can now use the <ckeditor> tag in the component template to include the rich text editor:

<ckeditor data="<p>Hello, world!</p>"></ckeditor>

The data attribute used in the example above is responsible for setting the editor’s data.

# Customizing CKEditor Preset or Version

By default, the CKEditor 4 Angular 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 setting the value of the editorUrl attribute in the template to point to the desired CKEditor script location:

<ckeditor editorUrl="https://your-website.example/ckeditor/ckeditor.js"></ckeditor>

Note that this attribute must be assigned before the first component is initialized.

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

<script src="my-custom-build/ckeditor.js"></script>
<script src="your-app-bundle.js"></script>

# Choosing the Editor Type

By default, starting from the stable 1.0.0 version, the CKEditor 4 Angular component creates a classic editor. To create an editor with a floating UI, change the type property to inline:

<ckeditor
    data="<p>Some initial data</p>"
    type="inline"
></ckeditor>

# Using the Div-based Editor Type

Before the 2.0.0 integration version there was also a separate divarea editor type (an inline editor with a fixed UI).

To use the divarea editor in 2.0.0 and later versions, you just need to include the Div Editing Area plugin in the editor configuration:

<ckeditor
    data="<p>Some initial data</p>"
    [config]="{ extraPlugins: 'divarea' }"
></ckeditor>

To use the divarea editor in versions prior 2.0.0 (up to 1.3.0), you have to change the editor type to divarea:

<ckeditor
    data="<p>Some initial data</p>"
    type="divarea"
></ckeditor>

# Integration with ngModel

The component implements the ControlValueAccessor interface and works with ngModel.

To use it, first create a model in your component:

@Component( {
    ...
} )
export class MyComponent {
    public model = {
        editorData: '<p>Hello, world!</p>'
    };
    ...
}

Then you can use the model in the template to enable the two-way data binding.

<ckeditor [(ngModel)]="model.editorData"></ckeditor>

# Supported @Input properties

The following @Input properties are supported by the CKEditor 4 Angular component:

# editorUrl

The URL address to ckeditor.js. Refer to Customising CKEditor Preset or Version for more information.

# config

Custom configuration can be passed to the editor with the config attribute passed to the <ckeditor> in the component template. The following example shows how to change the toolbar configuration:

<ckeditor
    data="<p>Editor' content</p>"
    [config]="{ toolbar: [ [ 'Bold' ] ] }"
></ckeditor>

All configuration options can be changed this way.

# data

The initial data of the WYSIWYG editor. It can be a static value:

<ckeditor data="<p>Hello, world!</p>"></ckeditor>

or a shared parent component’s property:

@Component( {
    ...
} )
export class MyComponent {
    public editorData = '<p>Hello, world!</p>';
}

<ckeditor [data]="editorData"></ckeditor>

# tagName

Specifies the tag name of the HTML element on which the WYSIWYG editor will be created.

The default tag is <textarea>.

<ckeditor tagName="textarea"></ckeditor>

# readOnly

The editor can be set to a read-only mode with the readOnly property:

<ckeditor
    data="<p>Editor's content</p>"
    readOnly="true"
></ckeditor>

This property takes precedence over the config.readOnly setting.

# Supported @Output properties

General note: Callbacks bound to each of the events are called with eventInfo. For importing and usage of the EventInfo interface see the change example.

The following @Output properties are supported by the CKEditor 4 Angular component:

# namespaceLoaded

Fires when the CKEDITOR namespace is loaded. It only triggers once, no matter how many CKEditor 4 components are initialized. Can be used for convenient changes in the namespace, e.g. for adding external plugins:

<ckeditor (namespaceLoaded)="onNamespaceLoaded($event)"></ckeditor>

import { CKEditor4 } from 'ckeditor4-angular/ckeditor';

@Component( {
    ...
} )
export class MyComponent {
    public onNamespaceLoaded( event: CKEditor4.EventInfo ) {
        // 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' );
    }
    ...
}

# ready

Fires when the editor is ready. It corresponds with the editor#instanceReady event.

# dataReady

Fires when the editor data is loaded, for example after switching from WYSIWYG mode or using the editor#setData() method. It corresponds with the editor#dataReady event.

# change

Fires when the content of the editor has changed. It corresponds with the editor#change event. For performance reasons this event may be called even when data has not really changed.

Please note that this event will only be fired when the Undo plugin is loaded. If you need to listen for editor changes (e.g. for two-way data binding), use the dataChange event instead.

<ckeditor (change)="onChange($event)"></ckeditor>

import { CKEditor4 } from 'ckeditor4-angular/ckeditor';

@Component( {
    ...
} )
export class MyComponent {
    public onChange( event: CKEditor4.EventInfo ) {
        console.log( event.editor.getData() );
    }
    ...
}

# dataChange

Fires when the content of the editor has changed. In contrast to change, it only emits when the data has really changed and thus it can be successfully used with [data] and two-way [(data)] binding.

# focus

Fires when the editor’s editable is focused. It corresponds with the editor#focus event.

# blur

Fires when the editing area of the editor is blurred. It corresponds with the editor#blur event.

# paste

Fires when the user initiates a paste action, but before the data is inserted into the editor. It corresponds with the editor#paste event.

# afterPaste

Fires after the paste event if the editor content was modified by a paste action. It corresponds with the editor#afterPaste event.

# dragStart

A facade for the native dragstart event. Fires when the native dragstart event occurs. It corresponds with the editor#dragstart event.

# dragEnd

A facade for the native dragend event. Fires when the native dragend event occurs. It corresponds with the editor#dragend event.

# drop

A facade for the native drop event. Fires when the native drop event occurs. It corresponds with the editor#drop event.

# fileUploadRequest

Fires when the file loader should send an XHR request. If the event is not stopped or canceled, the default request will be sent. It corresponds with the editor#fileUploadRequest event.

# fileUploadResponse

Fires when the file upload response is received and needs to be parsed. If the event is not stopped or canceled, the default response handler will be used. It corresponds with the editor#fileUploadResponse event.

# Editor Instance

In most cases there is no need to break the encapsulation provided by the CKEditor 4 Angular component as the WYSIWYG editor configuration and event handlers are configurable via the component’s properties. However, if you need access to the editor object, you can use the instance property of the component’s instance:

component.instance.getData();

Please note that this property is initialised asynchronously, when the component is ready.

# Types

CKEditor 4 types can be installed from @types/ckeditor. Note that they are not maintained by the CKEditor team, so we cannot guarantee that they are up to date.

# CKEditor 4 Angular Integration Demo

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