Contribute to this guideReport an issue

guideRich text editor component for Angular 2+

npm version

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

Currently, the CKEditor 5 component for Angular supports integrating CKEditor 5 only via builds. Integrating CKEditor 5 built from source is not possible yet due to the lack of ability to adjust webpack configuration in angular-cli.

While there is no support to integrate CKEditor 5 from source yet, you can still create a custom build of CKEditor 5 and include it in your Angular application.

# Quick start

In your existing Angular project, install the CKEditor 5 rich text editor component for Angular 2+:

npm install --save-dev @ckeditor/ckeditor5-angular

Install one of the official editor builds or create a custom one (e.g. if you want to install more plugins or customize something that cannot be controlled with the editor configuration).

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

npm install --save-dev @ckeditor/ckeditor5-build-classic

Note: You may need to allow external JavaScript in your project’s tsconfig.json for the builds to work properly:

"compilerOptions": {
    "allowJs": true
}

Now, add CKEditorModule to your application module imports:

import { CKEditorModule } from '@ckeditor/ckeditor5-angular';

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

Import the editor build in your Angular component and assign it to a public property so it becomes accessible in the template:

import * as ClassicEditor from '@ckeditor/ckeditor5-build-classic';

@Component( {
    ...
} )
export class MyComponent {
    public Editor = ClassicEditor;
    ...
}

Finally, use the <ckeditor> tag in the template to run the rich text editor:

<ckeditor [editor]="Editor" data="<p>Hello world!</p>"></ckeditor>

Rebuild your application and CKEditor 5 should greet you with “Hello world!”.

# Note: Using the Document editor build

If you want to use the Document editor build, you need to add the toolbar to the DOM manually.

import * as DecoupledEditor from '@ckeditor/ckeditor5-build-decoupled-document';

@Component( {
    ...
} )
export class MyComponent {
    public Editor = DecoupledEditor;

    public onReady( editor ) {
        editor.ui.view.editable.element.parentElement.insertBefore(
            editor.ui.view.toolbar.element,
            editor.ui.view.editable.element
        );
    }
}

And then, in the template:

<ckeditor [editor]="Editor" data="<p>Hello world!</p>" (ready)="onReady($event)"></ckeditor>

# Integration with ngModel

The component implements the ControlValueAccessor interface and works with the ngModel. Here is how to use it:

  1. Create some model in your component to share with the editor:

    @Component( {
        ...
    } )
    export class MyComponent {
        public model = {
            editorData: '<p>Hello world!</p>'
        };
        ...
    }
    
  2. Use the model in the template to enable a two–way data binding:

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

# Supported @Input properties

The following @Input properties are supported by the CKEditor 5 component for Angular 2+:

# editor (required)

The Editor which provides the static create() method to create an instance of the editor:

<ckeditor [editor]="Editor"></ckeditor>

# config

The configuration of the editor:

<ckeditor [config]="{ toolbar: [ 'heading', '|', 'bold', 'italic' ] }" ...></ckeditor>

# data

The initial data of the 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 editor will be created.

The default tag is <div>.

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

# disabled

Controls the editor’s read–only state:

@Component( {
    ...
} )
export class MyComponent {
    public isDisabled = false;
    ...
    toggleDisabled() {
        this.isDisabled = !this.isDisabled
    }
}
<ckeditor [disabled]="isDisabled" ...></ckeditor>

<button (click)="toggleDisabled()">
    {{ isDisabled ? 'Enable editor' : 'Disable editor' }}
</button>

# Supported @Output properties

The following @Output properties are supported by the CKEditor 5 component for Angular 2+:

# ready

Fired when the editor is ready. It corresponds with the editor#ready event. Fired with the editor instance.

# change

Fired when the content of the editor has changed. It corresponds with the editor.model.document#change:data event.
Fired with an object containing the editor and the CKEditor 5 change:data event object.

<ckeditor [editor]="Editor" (change)="onChange($event)"></ckeditor>
import * as ClassicEditor from '@ckeditor/ckeditor5-build-classic';
import { ChangeEvent } from '@ckeditor/ckeditor5-angular/ckeditor.component';

@Component( {
    ...
} )
export class MyComponent {
    public Editor = ClassicEditor;

    public onChange( { editor }: ChangeEvent ) {
        const data = editor.getData();

        console.log( data );
    }
    ...
}

# blur

Fired when the editing view of the editor is blurred. It corresponds with the editor.editing.view.document#blur event.
Fired with an object containing the editor and the CKEditor 5 blur event data.

# focus

Fired when the editing view of the editor is focused. It corresponds with the editor.editing.view.document#focus event.
Fired with an object containing the editor and the CKEditor 5 focus event data.

# Localization

CKEditor 5 can be localized in two steps.

# 1. Load translation files

First, you need to add translation files to the bundle. This step can be achieved in two ways:

  • By importing translations for given languages directly in your component file:

    import '@ckeditor/ckeditor5-build-classic/build/translations/de';
    import * as ClassicEditor from '@ckeditor/ckeditor5-build-classic';
    ...
    
  • By adding paths to translation files to the "scripts" array in angular.json:

    "architect": {
        "build": {
            "options": {
                "scripts": [ "node_modules/@ckeditor/ckeditor5-build-classic/build/translations/de.js" ]
            }
        }
    }
    

# 2. Configure the language

Then, you need to configure the editor to use the given language:

@Component( {
    ...
} )
export class MyComponent {
    public Editor = ClassicEditor;
    public config = {
        language: 'de'
    };
}

For advanced usage see the Setting UI language guide.

# Contributing and reporting issues

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