Skip to content
Permalink
master
Switch branches/tags
Go to file
 
 
Cannot retrieve contributors at this time
603 lines (468 sloc) 23.1 KB
menu-title category order
React component
builds-integration-frameworks
30

Rich text editor component for React

npm version

CKEditor 5 consists of {@link builds/guides/overview ready-to-use editor builds} and {@link framework/guides/overview CKEditor 5 Framework} upon which the builds are based.

The easiest way to use CKEditor 5 in your React application is by choosing one of the {@link builds/guides/overview#available-builds rich text editor builds}. Additionally, it is also possible to integrate CKEditor 5 built from source into your application. You can also use a customized editor built by using CKEditor 5 online builder in any React application.

Quick start

Install the CKEditor 5 WYSIWYG editor component for React and the {@link builds/guides/overview#available-builds editor build of your choice}.

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

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

Use the <CKEditor> component inside your project:

import React, { Component } from 'react';
import { CKEditor } from '@ckeditor/ckeditor5-react';
import ClassicEditor from '@ckeditor/ckeditor5-build-classic';

class App extends Component {
	render() {
		return (
			<div className="App">
				<h2>Using CKEditor 5 build in React</h2>
				<CKEditor
					editor={ ClassicEditor }
					data="<p>Hello from CKEditor 5!</p>"
					onReady={ editor => {
						// You can store the "editor" and use when it is needed.
						console.log( 'Editor is ready to use!', editor );
					} }
					onChange={ ( event, editor ) => {
						const data = editor.getData();
						console.log( { event, editor, data } );
					} }
					onBlur={ ( event, editor ) => {
						console.log( 'Blur.', editor );
					} }
					onFocus={ ( event, editor ) => {
						console.log( 'Focus.', editor );
					} }
				/>
			</div>
		);
	}
}

export default App;

Component properties

The <CKEditor> component supports the following properties:

  • editor (required) – The {@link module:core/editor/editor~Editor Editor} constructor to use.
  • data – The initial data for the created editor. See the {@link builds/guides/integration/basic-api#interacting-with-the-editor Basic API} guide.
  • config – The editor configuration. See the {@link builds/guides/integration/configuration Configuration} guide.
  • id – The editor ID. When this property changes, the component restarts the editor with new data instead of setting it on an initialized editor.
  • disabled – A Boolean value. The {@link module:core/editor/editor~Editor editor} is being switched to read-only mode if the property is set to true.
  • onReady – A function called when the editor is ready with an {@link module:core/editor/editor~Editor editor} instance. This callback is also called after the reinitialization of the component if an error occurred.
  • onChange – A function called when the editor data has changed. See the {@link module:engine/model/document~Document#event:change:data editor.model.document#change:data} event.
  • onBlur – A function called when the editor was blurred. See the {@link module:engine/view/document~Document#event:blur editor.editing.view.document#blur} event.
  • onFocus – A function called when the editor was focused. See the {@link module:engine/view/document~Document#event:focus editor.editing.view.document#focus} event.
  • onError – A function called when the editor has crashed during the initialization or during the runtime. It receives two arguments: the error instance and the error details. Error details is an object that contains two properties:
    • {String} phase: 'initialization'|'runtime' – Informs when the error has occurred (during the editor or context initialization, or after the initialization).
    • {Boolean} willEditorRestart – When true, it means that the editor component will restart itself.

The editor event callbacks (onChange, onBlur, onFocus) receive two arguments:

  1. An {@link module:utils/eventinfo~EventInfo EventInfo} object.
  2. An {@link module:core/editor/editor~Editor Editor} instance.

Context feature

The @ckeditor/ckeditor5-react package provides a ready-to-use component for the context feature that is useful when used together with some CKEditor 5 collaboration features.

// This sample assumes that the application is using a CKEditor 5 editor built from source.
import React, { Component } from 'react';
import { CKEditor, CKEditorContext } from '@ckeditor/ckeditor5-react';

import Context from '@ckeditor/ckeditor5-core/src/context';
import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';

class App extends Component {
	render() {
		return (
			<div className="App">
				<CKEditorContext context={ Context }>
					<h2>Using the CKeditor 5 context feature in React</h2>
					<CKEditor
						editor={ ClassicEditor }
						config={ {
							plugins: [ Paragraph, Bold, Italic, Essentials ],
							toolbar: [ 'bold', 'italic' ]
						} }
						data="<p>Hello from the first editor working with the context!</p>"
						onReady={ editor => {
							// You can store the "editor" and use when it is needed.
							console.log( 'Editor1 is ready to use!', editor );
						} }
					/>

					<CKEditor
						editor={ ClassicEditor }
						config={ {
							plugins: [ Paragraph, Bold, Italic, Essentials ],
							toolbar: [ 'bold', 'italic' ]
						} }
						data="<p>Hello from the first editor working with the context!</p>"
						onReady={ editor => {
							// You can store the "editor" and use when it is needed.
							console.log( 'Editor1 is ready to use!', editor );
						} }
					/>
				</CKEditorContext>
			</div>
		);
	}
}

Context feature properties

The CKEditorContext component supports the following properties:

  • context (required) – {@link module:core/context~Context The CKEditor 5 context class}.
  • config – The CKEditor 5 context configuration.
  • isLayoutReady – A property that delays the context creation when set to false. It creates the context and the editor children once it is true or unset. Useful when the CKEditor 5 annotations or a presence list are used.
  • id – The context ID. When this property changes, the component restarts the context with its editor and reinitializes it based on the current configuration.
  • onReady – A function called when the context is ready and all editors inside were initialized with the context instance. This callback is also called after the reinitialization of the component if an error has occurred.
  • onError – A function called when the context has crashed during the initialization or during the runtime. It receives two arguments: the error instance and the error details. Error details is an object that contains two properties:
    • {String} phase: 'initialization'|'runtime' – Informs when the error has occurred (during the editor or context initialization, or after the initialization).
    • {Boolean} willContextRestart – When true, it means that the context component will restart itself.
An example build that exposes both context and classic editor can be found in the [CKEditor 5 collaboration sample](https://github.com/ckeditor/ckeditor5-collaboration-samples/blob/master/comments-outside-of-editor).

Customizing the builds

{@link builds/guides/overview CKEditor 5 builds} come ready to use, with a set of built-in plugins and a predefined configuration. While you can change the configuration easily by using the config property of the <CKEditor> component which allows you to change the {@link features/toolbar toolbar} or {@link builds/guides/integration/configuration#removing-features remove some plugins}, in order to add plugins you need to rebuild the editor.

There are three main ways to do that.

  • {@link builds/guides/development/custom-builds Customize one of the existing builds}.

    This option does not require any changes in your project's configuration. You will create a new build somewhere next to your project and include it like you included one of the existing builds. Therefore, it is the easiest way to add missing features.

    Read more about this method in the {@link builds/guides/integration/installing-plugins Installing plugins} guide.

  • Use the CKEditor 5 online builder.

    Create your own CKEditor 5 build with customized plugins, toolbar and language in 5 simple steps.

    If you want to use the [CKEditor 5 online builder](https://ckeditor.com/ckeditor-5/online-builder/), make sure that the [watchdog feature](https://ckeditor.com/docs/ckeditor5/latest/features/watchdog.html) is not selected. The React integration comes with the watchdog feature already integrated into the core.

    Read more about this option in the Integrating a build from the online builder section.

  • {@link builds/guides/integration/advanced-setup Integrate the editor from source}.

    In this approach you will include a CKEditor 5 built from source — so you will choose the editor creator you want and the list of plugins, etc. It is more powerful and creates a tighter integration between your application and the WYSIWYG editor, however, it requires adjusting your webpack.config.js to CKEditor 5 needs.

    Read more about this option in the Integrating CKEditor 5 from source section.

Using the document editor build

If you use the {@link framework/guides/document-editor document (decoupled) editor}, you need to {@link module:editor-decoupled/decouplededitor~DecoupledEditor.create add the toolbar to the DOM manually}:

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

class App extends Component {
	editor = null;

	render() {
		return (
			<div className="App">
				<h2>CKEditor 5 using a custom build - decoupled editor</h2>
				<CKEditor
					onReady={ editor => {
						console.log( 'Editor is ready to use!', editor );

						// Insert the toolbar before the editable area.
						editor.ui.getEditableElement().parentElement.insertBefore(
							editor.ui.view.toolbar.element,
							editor.ui.getEditableElement()
						);

						this.editor = editor;
					} }
					onError={ ( { willEditorRestart } ) => {
						// If the editor is restarted, the toolbar element will be created once again.
						// The `onReady` callback will be called again and the new toolbar will be added.
						// This is why you need to remove the older toolbar.
						if ( willEditorRestart ) {
							this.editor.ui.view.toolbar.element.remove();
						}
					} }
					onChange={ ( event, editor ) => console.log( { event, editor } ) }
					editor={ DecoupledEditor }
					data="<p>Hello from CKEditor 5's decoupled editor!</p>"
					config={ /* the editor configuration */ }
				/>
		);
	}
}

export default App;

Using the editor with collaboration plugins

The easiest way to integrate collaboration plugins in a React application is to build the editor from source including the collaboration plugins together with the React application.

For such a scenario we provide a few ready-to-use integrations featuring collaborative editing in React applications:

It is not mandatory to build applications on top of the above samples, however, they should help you get started.

Note: These integrations are meant to be as simple as possible, so they do not use the Create React App CLI. However, you should have no problem starting from CRA after reading the sections below.

Integrating a build from the online builder

This guide assumes that you have created a zip archive with the editor built using the CKEditor 5 online builder.

The directory with the editor's build cannot be placed inside the src/ directory because Node could return an error:

FATAL ERROR: Ineffective mark-compacts near heap limit Allocation failed - JavaScript heap out of memory

Because of that, we recommend placing the directory next to the src/ and node_modules/ folders:

├── ckeditor5
│   ├── build
│   ├── sample
│   ├── src
│   ├── ...
│   ├── package.json
│   └── webpack.config.js
├── node_modules
├── public
├── src
├── ...
└── package.json

Then, add the package located in the ckeditor5 directory as a dependency of your project:

yarn add file:./ckeditor5

Now, import the build in your application:

import React, { Component } from 'react';
import Editor from 'ckeditor5-custom-build/build/ckeditor';
import { CKEditor } from '@ckeditor/ckeditor5-react'

const editorConfiguration = {
	toolbar: [ 'bold', 'italic' ]
};

class App extends Component {
	render() {
		return (
			<div className="App">
				<h2>Using CKEditor 5 from online builder in React</h2>
				<CKEditor
					editor={ Editor }
					config={ editorConfiguration }
					data="<p>Hello from CKEditor 5!</p>"
					onReady={ editor => {
						// You can store the "editor" and use when it is needed.
						console.log( 'Editor is ready to use!', editor );
					} }
					onChange={ ( event, editor ) => {
						const data = editor.getData();
						console.log( { event, editor, data } );
					} }
					onBlur={ ( event, editor ) => {
						console.log( 'Blur.', editor );
					} }
					onFocus={ ( event, editor ) => {
						console.log( 'Focus.', editor );
					} }
				/>
			</div>
		);
	}
}

export default App;

Integrating CKEditor 5 built from source

Integrating the rich text editor from source allows you to use the full power of the {@link framework/guides/overview CKEditor 5 Framework}.

This guide assumes that you are using the Create React App CLI as your boilerplate and it goes through adjusting it to fit CKEditor 5 needs. If you use your custom webpack setup, please read more about {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source including CKEditor 5 built from source}.

Using create-react-app@3+

The configuration needs to be ejected to make it possible to customize the webpack configuration. In order to be able to build CKEditor 5 from source, you need to tell webpack how to handle CKEditor 5's SVG and CSS files (by adding loaders configuration). Additionally, you need to exclude the CKEditor 5 source from the existing loaders.

You can see all the changes described below in this example project: https://github.com/ckeditor/ckeditor5-react-example/.

Create a sample application using create-react-app@3+ first:

npx create-react-app ckeditor5-react-example && cd ckeditor5-react-example

Now you can eject the configuration (you can find more information about ejecting here):

yarn eject

Installing missing dependencies

Before you start modifying the webpack configuration, first install some CKEditor 5 dependencies that you will need:

yarn add \
	raw-loader@3 \
	@ckeditor/ckeditor5-dev-utils \
	@ckeditor/ckeditor5-theme-lark \
	@ckeditor/ckeditor5-react \
	@ckeditor/ckeditor5-editor-classic \
	@ckeditor/ckeditor5-essentials \
	@ckeditor/ckeditor5-paragraph \
	@ckeditor/ckeditor5-basic-styles

Modifying the webpack configuration

Once you ejected the configuration and installed dependencies, you can now edit the webpack configuration (config/webpack.config.js).

First, import an object that provides a utility for creating the configuration for PostCSS:

const { styles } = require( '@ckeditor/ckeditor5-dev-utils' );

Then, add two new elements to the exported object under the module.rules array (as new items of the oneOf array). These are SVG and CSS loaders required to handle the CKEditor 5 source:

{
	test: /ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/,
	use: [ 'raw-loader' ]
},
{
	test: /ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css$/,
	use: [
		{
			loader: 'style-loader',
			options: {
				injectType: 'singletonStyleTag',
				attributes: {
					'data-cke': true
				}
			}
		},
		{
			loader: 'postcss-loader',
			options: styles.getPostCssConfig( {
				themeImporter: {
					themePath: require.resolve( '@ckeditor/ckeditor5-theme-lark' )
				},
				minify: true
			} )
		}
	]
},

Now you need to exclude CSS files used by CKEditor 5 from the project's CSS loader.

First, find a loader that starts its definition with the following code: test: cssRegex. Then modify it:

{
	test: cssRegex,
	exclude: [
		cssModuleRegex,
		/ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css$/,
	],
	// (...)
}

Below it, you will find another loader that handles the CSS files. You need to disable it for CKEditor 5 CSS as well. Its definition starts with test: cssModuleRegex:

{
	test: cssModuleRegex,
	exclude: [
		/ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css$/,
	],
	// (...)
}

Finally, exclude CKEditor 5 SVG and CSS files from file-loader. Find the last item in the module.rules array which should be the file-loader configuration, and modify it so it looks like this:

{
	loader: require.resolve( 'file-loader' ),
	// Exclude `js` files to keep the "css" loader working as it injects
	// its runtime that would otherwise be processed through the "file" loader.
	// Also exclude `html` and `json` extensions so they get processed
	// by webpack's internal loaders.
	exclude: [
		/\.(js|mjs|jsx|ts|tsx)$/,
		/\.html$/,
		/\.json$/,
		/ckeditor5-[^/\\]+[/\\]theme[/\\]icons[/\\][^/\\]+\.svg$/,
		/ckeditor5-[^/\\]+[/\\]theme[/\\].+\.css$/
	],
	options: {
		name: 'static/media/[name].[hash:8].[ext]',
	}
}

Using CKEditor 5 source

Once your configuration is updated, you can use CKEditor 5 directly from source. Test it by editing src/App.js:

import React, { Component } from 'react';

import { CKEditor } from '@ckeditor/ckeditor5-react';

// NOTE: Use the editor from source (not a build)!
import ClassicEditor from '@ckeditor/ckeditor5-editor-classic/src/classiceditor';

import Essentials from '@ckeditor/ckeditor5-essentials/src/essentials';
import Bold from '@ckeditor/ckeditor5-basic-styles/src/bold';
import Italic from '@ckeditor/ckeditor5-basic-styles/src/italic';
import Paragraph from '@ckeditor/ckeditor5-paragraph/src/paragraph';

const editorConfiguration = {
	plugins: [ Essentials, Bold, Italic, Paragraph ],
	toolbar: [ 'bold', 'italic' ]
};

class App extends Component {
	render() {
		return (
			<div className="App">
				<h2>Using CKEditor 5 from source in React</h2>
				<CKEditor
					editor={ ClassicEditor }
					config={ editorConfiguration }
					data="<p>Hello from CKEditor 5!</p>"
					onReady={ editor => {
						// You can store the "editor" and use when it is needed.
						console.log( 'Editor is ready to use!', editor );
					} }
					onChange={ ( event, editor ) => {
						const data = editor.getData();
						console.log( { event, editor, data } );
					} }
					onBlur={ ( event, editor ) => {
						console.log( 'Blur.', editor );
					} }
					onFocus={ ( event, editor ) => {
						console.log( 'Focus.', editor );
					} }
				/>
			</div>
		);
	}
}

export default App;

Finally, you can see your application live:

yarn start

You can read more about using CKEditor 5 from source in the {@link builds/guides/integration/advanced-setup#scenario-2-building-from-source Advanced setup guide}.

Localization

CKEditor 5 supports {@link features/ui-language multiple UI languages}, and so does the official React component. Follow the instructions below to translate CKEditor 5 in your React application.

Ready-to-use builds

When using one of the {@link builds/guides/overview#available-builds official editor builds} or the editor built by the online builder, you need to import the translations first:

Official editor builds:

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

// Import translations for the German language.
import '@ckeditor/ckeditor5-build-classic/build/translations/de';

// ...

The editor build from the online builder:

import Editor from 'ckeditor5-custom-build/build/ckeditor';

// Import translations for the German language.
import 'ckeditor5-custom-build/build/translations/de';

Then, {@link builds/guides/integration/configuration configure} the language of the editor in the component:

<CKEditor
	config={ {
		// Use the German language for this editor.
		language: 'de',

		// ...
	} }
	editor={ ClassicEditor }
	data="<p>Hello from CKEditor 5!</p>"
/>

For more information, please refer to the {@link features/ui-language Setting the UI language} guide.

CKEditor 5 built from source

Using the editor built from source requires you to modify the webpack configuration. First, install the official webpack plugin that allows localizing editor builds:

yarn add @ckeditor/ckeditor5-dev-webpack-plugin --dev

Then, add the installed plugin to the webpack configuration:

// webpack.config.js
'use strict';

// ...
const CKEditorWebpackPlugin = require( '@ckeditor/ckeditor5-dev-webpack-plugin' );

module.exports = {
	// ...

	plugins: [
		// ....

		new CKEditorWebpackPlugin( {
			// The UI language. Language codes follow the https://en.wikipedia.org/wiki/ISO_639-1 format.
			language: 'de',
			addMainLanguageTranslationsToAllAssets: true
		} ),

		// ....
	],

	// ...
};

After building the application, CKEditor 5 will run with the UI translated into the specified language.

For more information, please refer to the {@link features/ui-language Setting the UI language} guide.

Contributing and reporting issues

The source code of rich text editor component for React is available on GitHub in https://github.com/ckeditor/ckeditor5-react.