menu-title | meta-title | category | order |
---|---|---|---|
Angular |
Angular rich text editor component | CKEditor 5 documentation |
installation |
30 |
{@snippet installation/integrations/framework-integration}
Angular is a TypeScript-based, open-source, single-page web application framework. The CKEditor 5 component for Angular supports integrating different editor types.
Starting from version 6.0.0 of this package, you can use native type definitions provided by CKEditor 5. Check the details about {@link getting-started/setup/typescript-support TypeScript support}.Because of the breaking changes in the Angular library output format, the @ckeditor/ckeditor5-angular
package is released in the following versions to support various Angular ecosystems:
CKEditor 5 version | Angular version | Details |
---|---|---|
Actively supported versions | ||
^6 |
13+ |
Requires CKEditor 5 in version 37 or higher. |
Past releases (no longer maintained) | ||
^5 |
13+ |
Requires Angular in version 13+ or higher. Lower versions are no longer maintained. |
^5 |
13+ |
Requires Angular in version 13+ or higher. Lower versions are no longer maintained. |
^4 |
9.1+ |
Requires CKEditor 5 in version 34 or higher. |
^3 |
9.1+ |
Requires Node.js in version 14 or higher. |
^2 |
9.1+ |
Migration to TypeScript 4. Declaration files are not backward compatible. |
^1 |
5.x - 8.x |
Angular versions are no longer maintained. |
All available Angular versions are listed on npm, where they can be pulled from.
The easiest way to use CKEditor 5 in your Angular application is by configuring it with CKEditor 5 Builder and integrating it with your application. Builder offers an easy-to-use user interface to help you configure, preview, and download the editor suited to your needs. You can easily select:
- the features you need,
- the preferred framework (React, Angular, Vue or Vanilla JS),
- the preferred distribution method.
You get ready-to-use code tailored to your needs!
This guide assumes you already have a Angular project. To create such a project, you can use Angular CLI. Refer to the Angular documentation to learn more.
First, install the CKEditor 5 packages:
ckeditor5
– package with open-source plugins and features.ckeditor5-premium-features
– package with premium plugins and features.
Depending on your configuration and chosen plugins, you may need to install the first or both packages.
npm install ckeditor5 ckeditor5-premium-features
Then, install the CKEditor 5 WYSIWYG editor component for Angular:
npm install @ckeditor/ckeditor5-angular
The following setup differs depending on the type of component you use.
If you want to use NGModule components, add the CKEditorModule
to the imports
array. It will make the CKEditor 5 component available in your Angular application.
// app.module.ts
import { NgModule } from '@angular/core';
import { BrowserModule } from '@angular/platform-browser';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';
import { AppComponent } from './app.component';
@NgModule( {
declarations: [
AppComponent
],
imports: [
BrowserModule,
CKEditorModule
],
providers: [],
bootstrap: [ AppComponent ]
} )
export class AppModule { }
Then, import the editor in your Angular component and assign it to a public
property to make it accessible from the template. The below example shows how to use the component with open-source and premium plugins.
// app.component.ts
import { Component } from '@angular/core';
import { ClassicEditor, Bold, Essentials, Italic, Mention, Paragraph, Undo } from 'ckeditor5';
import { SlashCommand } from 'ckeditor5-premium-features';
import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';
@Component( {
selector: 'app-root',
templateUrl: './app.component.html',
styleUrls: [ './app.component.css' ]
} )
export class AppComponent {
title = 'angular';
public Editor = ClassicEditor;
public config = {
toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
plugins: [
Bold, Essentials, Italic, Mention, Paragraph, SlashCommand, Undo
],
licenseKey: '<YOUR_LICENSE_KEY>',
mention: {
// Mention configuration
}
}
}
Finally, use the <ckeditor>
tag in the template to run the rich text editor:
<!-- app.component.html -->
<ckeditor [editor]="Editor" [config]="config" data="<p>Hello, world!</p>"></ckeditor>
Standalone components provide a simplified way to build Angular applications. They are enabled in Angular 17 by default. Standalone components aim to simplify the setup and reduce the need for NGModules
. That is why you do not need such a module in this case.
Instead, add the CKEditorModule
to the imports in your app component. The component needs the standalone
option set to true
.
import { Component } from '@angular/core';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';
import { ClassicEditor, Bold, Essentials, Italic, Mention, Paragraph, Undo } from 'ckeditor5';
import { SlashCommand } from 'ckeditor5-premium-features';
import 'ckeditor5/ckeditor5.css';
import 'ckeditor5-premium-features/ckeditor5-premium-features.css';
@Component( {
selector: 'app-root',
templateUrl: './app.component.html',
imports: [ CKEditorModule ],
standalone: true
} )
export class AppComponent {
title = 'angular';
public Editor = ClassicEditor;
public config = {
toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
plugins: [
Bold, Essentials, Italic, Mention, Paragraph, SlashCommand, Undo
],
licenseKey: '<YOUR_LICENSE_KEY>',
mention: {
// Mention configuration
}
}
}
Then, use the <ckeditor>
tag in the template to run the rich text editor:
<!-- app.component.html -->
<ckeditor [editor]="Editor" [config]="config" data="<p>Hello, world!</p>"></ckeditor>
The following @Input
properties are supported by the CKEditor 5 rich text editor component for Angular:
The {@link getting-started/setup/editor-lifecycle Editor
} which provides the static {@link module:core/editor/editor~Editor.create create()
} method to create an instance of the editor:
<ckeditor [editor]="Editor"></ckeditor>
The {@link module:core/editor/editorconfig~EditorConfig configuration} of the editor:
<ckeditor [config]="{ toolbar: [ 'heading', '|', 'bold', 'italic' ] }"></ckeditor>
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>
The tag name of the HTML element on which the rich text editor will be created.
The default tag is <div>
.
<ckeditor tagName="textarea"></ckeditor>
Controls the editor's {@link module:core/editor/editor~Editor#isReadOnly 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>
An instance of the {@link module:watchdog/contextwatchdog~ContextWatchdog ContextWatchdog
} class that is responsible for providing the same context to multiple editor instances and restarting the whole structure in case of crashes.
import CKSource from 'path/to/custom/build';
const Context = CKSource.Context;
const Editor = CKSource.Editor;
const ContextWatchdog = CKSource.ContextWatchdog;
@Component( {
// ...
} )
export class MyComponent {
public editor = Editor;
public watchdog: any;
public ready = false;
ngOnInit() {
const contextConfig = {};
this.watchdog = new ContextWatchdog( Context );
this.watchdog.create( contextConfig )
.then( () => {
this.ready = true;
} );
}
}
<div *ngIf="ready">
<ckeditor [watchdog]="watchdog"></ckeditor>
<ckeditor [watchdog]="watchdog"></ckeditor>
<ckeditor [watchdog]="watchdog"></ckeditor>
</div>
If the watchdog
property is not used, {@link module:watchdog/editorwatchdogEditorWatchdog WatchdogConfig config} to that watchdog.EditorWatchdog
} will be used by default. editorWatchdogConfig
property allows for passing a {@link module:watchdog/watchdog
@Component( {
// ...
} )
export class MyComponent {
public myWatchdogConfig = {
crashNumberLimit: 5,
// ...
};
// ...
}
<ckeditor [editorWatchdogConfig]="myWatchdogConfig"></ckeditor>
Allows disabling the two-way data binding mechanism. The default value is false
.
The reason for the introduction of this option are performance issues in large documents. By default, while using the ngModel
directive, whenever the editor's data is changed, the component must synchronize the data between the editor instance and the connected property. This results in calling the {@link module:core/editor/editor~Editor#getData editor.getData()
} function, which causes a massive slowdown while typing in large documents.
This option allows the integrator to disable the default behavior and only call the {@link module:core/editor/editor~Editor#getData editor.getData()
} method on demand, which prevents the slowdowns. You can read more in the relevant issue.
The following @Output
properties are supported by the CKEditor 5 rich text editor component for Angular:
Fired when the editor is ready. It corresponds with the editor#ready
event.
It is fired with the editor instance.
Note that this method might be called multiple times. Apart from initialization, it is also called whenever the editor is restarted after a crash. Do not keep the reference to the editor instance internally, because it will change in case of restart. Instead, you should use watchdog.editor
property.
Fired when the content of the editor has changed. It corresponds with the {@link module:engine/model/document~Document#event:change:data editor.model.document#change:data
} event.
It is fired with an object containing the editor and the CKEditor 5 change:data
event object.
<ckeditor [editor]="Editor" (change)="onChange($event)"></ckeditor>
import { ClassicEditor } from 'ckeditor5';
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 );
}
// ...
}
Fired when the editing view of the editor is blurred. It corresponds with the {@link module:engine/view/document~Document#event:blur editor.editing.view.document#blur
} event.
It is fired with an object containing the editor and the CKEditor 5 blur
event data.
Fired when the editing view of the editor is focused. It corresponds with the {@link module:engine/view/document~Document#event:focus editor.editing.view.document#focus
} event.
It is fired with an object containing the editor and the CKEditor 5 focus
event data.
Fired when the editor crashes. Once the editor is crashed, the internal watchdog mechanism restarts the editor and fires the ready event.
Prior to ckeditor5-angular `v7.0.1`, this event was not fired for crashes during the editor initialization.The component implements the ControlValueAccessor
interface and works with the ngModel
. Here is how to use it:
Create some model in your component to share with the editor:
@Component( {
// ...
} )
export class MyComponent {
public model = {
editorData: '<p>Hello, world!</p>'
};
// ...
}
Use the model in the template to enable a two–way data binding:
<ckeditor [(ngModel)]="model.editorData" [editor]="Editor"></ckeditor>
The CKEditor 5 rich text editor component for Angular can be styled using the component style sheet or using a global style sheet. See how to set the CKEditor 5 component's height using these two approaches.
First, create a (S)CSS file in the parent component's directory and style the given editor's part preceded by the :host
and ::ng-deep
pseudo selectors:
/* src/app/app.component.css */
:host ::ng-deep .ck-editor__editable_inline {
min-height: 500px;
}
Then in the parent component add the relative path to the above style sheet:
/* src/app/app.component.ts */
@Component( {
// ...
styleUrls: [ './app.component.css' ]
} )
To style the component using a global style sheet, first, create it:
/* src/styles.css */
.ck-editor__editable_inline {
min-height: 500px;
}
Then, add it in the angular.json
configuration file:
"architect": {
"build": {
"options": {
"styles": [
{ "input": "src/styles.css" }
]
}
}
}
To display {@link features/editor-placeholder the placeholder} in the main editable element, set the placeholder
field in the CKEditor 5 rich text editor component configuration:
@Component( {
// ...
} )
export class MyComponent {
public config = {
placeholder: 'Type the content here!'
}
}
The CKEditor 5 rich text editor component provides all the functionality needed for most use cases. When access to the full CKEditor 5 API is needed you can get the editor instance with an additional step.
To do this, create a template reference variable #editor
pointing to the <ckeditor>
component:
<ckeditor #editor [editor]="Editor"></ckeditor>
Then get the <ckeditor>
component using a property decorated by @ViewChild( 'editor' )
and access the editor instance when needed:
@Component()
export class MyComponent {
@ViewChild( 'editor' ) editorComponent: CKEditorComponent;
public getEditor() {
// Warning: This may return "undefined" if the editor is hidden behind the `*ngIf` directive or
// if the editor is not fully initialised yet.
return this.editorComponent.editorInstance;
}
}
If you want to use the {@link framework/document-editor document (decoupled) editor}, you need to {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create add the toolbar to the DOM manually}:
// app.component.ts
import { Component } from '@angular/core';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';
import { DecoupledEditor, Essentials, Italic, Paragraph, Bold, Undo } from 'ckeditor5';
import 'ckeditor5/ckeditor5.css';
@Component( {
selector: 'app-root',
templateUrl: './app.component.html',
imports: [ CKEditorModule ],
standalone: true
} )
export class AppComponent {
title = 'angular';
public Editor = DecoupledEditor;
public config = {
plugins: [ Bold, Essentials, Italic, Paragraph, Undo ],
toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
}
public onReady( editor: DecoupledEditor ): void {
const element = editor.ui.getEditableElement()!;
const parent = element.parentElement!;
parent.insertBefore(
editor.ui.view.toolbar.element!,
element
);
}
}
And then, link the method in the template:
<!-- app.component.html -->
<ckeditor [editor]="Editor" data="<p>Hello, world!</p>" (ready)="onReady($event)"></ckeditor>
We provide a few ready-to-use integrations featuring collaborative editing in Angular applications:
- CKEditor 5 with real-time collaboration features
- CKEditor 5 with real-time collaboration and revision history features
- CKEditor 5 with the revision history feature
- CKEditor 5 with the track changes feature
It is not mandatory to build applications on top of the above samples, however, they should help you get started.
CKEditor 5 supports multiple UI languages, and so does the official Angular component. Follow the instructions below to translate CKEditor 5 in your Angular application.
Similarly to CSS style sheets, both packages have separate translations. Import them as shown in the example below. Then, pass them to the translations array of the config
property.
import { Component } from '@angular/core';
import { CKEditorModule } from '@ckeditor/ckeditor5-angular';
import { ClassicEditor } from 'ckeditor5';
// More imports...
import coreTranslations from 'ckeditor5/translations/es.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/es.js';
// style sheets imports...
@Component( {
selector: 'app-root',
templateUrl: './app.component.html',
imports: [ CKEditorModule ],
standalone: true
} )
export class AppComponent {
title = 'angular';
public Editor = ClassicEditor;
public config = {
translations: [ coreTranslations, premiumFeaturesTranslations ]
}
}
For advanced usage see the {@link getting-started/setup/ui-language Setting the UI language} guide.
The source code of the CKEditor 5 rich text editor component for Angular is available on GitHub in https://github.com/ckeditor/ckeditor5-angular.