React rich text editor component

React lets you build user interfaces out of individual pieces called components. CKEditor 5 can be used as one of such components.

# Quick start

# Setting up the project

This guide assumes you have a React project. You can create a basic React project using Vite. Refer to the React documentation to learn how to set up a project in the framework.

# Installing from npm

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

npm install @ckeditor/ckeditor5-react

Use the <CKEditor> component inside your project. The below example shows how to use the component with open-source and premium plugins.

import { CKEditor } from '@ckeditor/ckeditor5-react';
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';

function App() {
    return (
        <CKEditor
            editor={ ClassicEditor }
            config={ {
                toolbar: {
                    items: [ 'undo', 'redo', '|', 'bold', 'italic' ],
                },
                plugins: [
                    Bold, Essentials, Italic, Mention, Paragraph, SlashCommand, Undo
                ],
                licenseKey: '<YOUR_LICENSE_KEY>',
                mention: {
                    // Mention configuration
                },
                initialData: '<p>Hello from CKEditor 5 in React!</p>',
            } }
        />
    );
}

export default App;

Remember to import the necessary style sheets. The ckeditor5 package contains the styles for open-source features, while the ckeditor5-premium-features package contains the premium features styles.

# Component properties

The <CKEditor> component supports the following properties:

• editor (required) – The Editor constructor to use.
• data – The initial data for the created editor. See the Getting and setting data guide.
• config – The editor configuration. See the 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 editor is being switched to read-only mode if the property is set to true.
• disableWatchdog – A Boolean value. If set to true, the watchdog feature will be disabled. It is set to false by default.
• watchdogConfig – Configuration object for the watchdog feature.
• onReady – A function called when the editor is ready with an editor instance. This callback is also called after the reinitialization of the component if an error occurred.
• onAfterDestroy – A function called after the successful destruction of an editor instance rendered by the component. This callback is also triggered after the editor has been reinitialized after an error. The component is not guaranteed to be mounted when this function is called.
• onChange – A function called when the editor data has changed. See the editor.model.document#change:data event.
• onBlur – A function called when the editor was blurred. See the editor.editing.view.document#blur event.
• onFocus – A function called when the editor was focused. See the 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 EventInfo object.
2. An 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.

import { ClassicEditor, Context, Bold, Essentials, Italic, Paragraph, ContextWatchdog } from 'ckeditor5';
import { CKEditor, CKEditorContext } from '@ckeditor/ckeditor5-react';

import 'ckeditor5/ckeditor5.css';

function App() {
  return (
    <CKEditorContext
        context={ Context }
        contextWatchdog={ ContextWatchdog }
        onChangeInitializedEditors={ ( editors ) => {
            console.info( editors.editor1?.instance, editors.editor1?.yourAdditionalData );
        } }
    >
      <CKEditor
        editor={ ClassicEditor }
        config={ {
          plugins: [ Essentials, Bold, Italic, Paragraph ],
          toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ],
        } }
        data='<p>Hello from the first editor working with the context!</p>'
        contextItemMetadata={{
            name: 'editor1',
            yourAdditionalData: 2
        }}
        onReady={ ( editor ) => {
          // You can store the "editor" and use when it is needed.
          console.log( 'Editor 1 is ready to use!', editor );
        } }
      />

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

export default App;

The CKEditorContext component supports the following properties:

• context (required) – The CKEditor 5 context class.
• contextWatchdog (required) – The Watchdog 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.
• onChangeInitializedEditors – A function called when any editor is initialized or destroyed in the tree. It receives a dictionary of fully initialized editors, where the key is the value of the contextItemMetadata.name property set on the CKEditor component. The editor’s ID is the key if the contextItemMetadata property is absent. Additional data can be added to the contextItemMetadata in the CKEditor component, which will be passed to the onChangeInitializedEditors function.
• onReady – A function called when the context is initialized but before the editors in the tree are set up. After this function is executed, you can track additions and removals in the context tree using the context.editors.on('change', () => {}) method.
• 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.

# How to?

# Using the document editor type

If you use the document (decoupled) editor, you need to add the toolbar to the DOM manually:

import { useEffect, useRef, useState } from 'react';
import { DecoupledEditor, Bold, Essentials, Italic, Paragraph } from 'ckeditor5';
import { CKEditor } from '@ckeditor/ckeditor5-react';

import 'ckeditor5/ckeditor5.css';

function App() {
    const editorToolbarRef = useRef( null );
    const [ isMounted, setMounted ] = useState( false );

    useEffect( () => {
        setMounted( true );

        return () => {
            setMounted( false );
        };
    }, [] );

    return (
        <div>
            <div ref={ editorToolbarRef }></div>
            <div>
                { isMounted && (
                    <CKEditor
                        editor={ DecoupledEditor }
                        data='<p>Hello from CKEditor 5 decoupled editor!</p>'
                        config={ {
                            plugins: [ Bold, Italic, Paragraph, Essentials ],
                            toolbar: [ 'undo', 'redo', '|', 'bold', 'italic' ]
                        } }
                        onReady={ ( editor ) => {
                            if ( editorToolbarRef.current ) {
                                editorToolbarRef.current.appendChild( editor.ui.view.toolbar.element );
                            }
                        }}
                        onAfterDestroy={ ( editor ) => {
                            if ( editorToolbarRef.current ) {
                                Array.from( editorToolbarRef.current.children ).forEach( child => child.remove() );
                            }
                        }}
                    />
                ) }
            </div>
        </div>
    );
}

export default App;

# Using the editor with collaboration plugins

We provide a few ready-to-use integrations featuring collaborative editing in React applications:

• CKEditor 5 with real-time collaboration features and revision history features
• CKEditor 5 with offline comments, track changes and revision history features

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

# Localization

CKEditor 5 supports multiple UI languages, and so does the official React component. Follow the instructions below to translate CKEditor 5 in your React 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 inside the config prop in the CKEditor 5 component.

import { ClassicEditor } from 'ckeditor5';
import { CKEditor } from '@ckeditor/ckeditor5-react';
// More imports...

import coreTranslations from 'ckeditor5/translations/es.js';
import premiumFeaturesTranslations from 'ckeditor5-premium-features/translations/es.js';

// Style sheets imports...

function App() {
    return (
        <CKEditor
            editor={ ClassicEditor }
            config={ {
                translations: [ coreTranslations, premiumFeaturesTranslations ],
                initialData: '<p>Hola desde CKEditor 5 en React!</p>',
            } }
        />
    );
}

export default App;

For more information, please refer to the Setting the UI language guide.

# Jest testing

Jest is the default test runner used by many React apps. Unfortunately, Jest does not use a real browser. Instead, it runs tests in Node.js that uses JSDOM. JSDOM is not a complete DOM implementation, and while it is sufficient for standard apps, it cannot polyfill all the DOM APIs that CKEditor 5 requires.

For testing CKEditor 5, it is recommended to use testing frameworks that utilize a real browser and provide a complete DOM implementation. Some popular options include:

• Vitest
• Playwright
• Cypress

These frameworks offer better support for testing CKEditor 5 and provide a more accurate representation of how the editor behaves in a real browser environment.

If this is not possible and you still want to use Jest, you can mock some of the required APIs. Below is an example of how to mock some of the APIs used by CKEditor 5:

import React, { useRef } from 'react';
import { render, waitFor, screen } from '@testing-library/react';
import { userEvent } from '@testing-library/user-event';

import { DecoupledEditor, Essentials, Paragraph } from 'ckeditor5';
import { CKEditor } from '@ckeditor/ckeditor5-react';

beforeAll( () => {
    window.scrollTo = jest.fn();

    window.ResizeObserver = class ResizeObserver {
        observe() {}
        unobserve() {}
        disconnect() {}
    };

    for ( const key of [ 'InputEvent', 'KeyboardEvent' ] ) {
        window[ key ].prototype.getTargetRanges = () => {
            const range = new StaticRange( {
                startContainer: document.body.querySelector( '.ck-editor__editable p' ),
                startOffset: 0,
                endContainer: document.body.querySelector( '.ck-editor__editable p' ),
                endOffset: 0
            } );

            return [ range ];
        };
    }

    Range.prototype.getClientRects = () => ( {
        item: () => null,
        length: 0,
        [ Symbol.iterator ]: function* () {}
    } );
} );

const SomeComponent = ( { value, onChange } ) => {
    const editorRef = useRef();

    return (
        <div
            style={{
                border: '1px solid black',
                padding: 10,
            }}
        >
            <CKEditor
                editor={ DecoupledEditor }
                config={{
                    plugins: [ Essentials, Paragraph ],
                }}
                onReady={ (editor) => {
                    editorRef.current = editor;
                } }
                data={ value }
                onChange={ () => {
                    onChange( editorRef.current?.getData() );
                } }
            />
        </div>
    );
};

it( 'renders', async () => {
    render( <SomeComponent value="this is some content" /> );

    await waitFor( () => expect( screen.getByText( /some content/ ) ).toBeTruthy());
} );

it( 'updates', async () => {
    const onChange = jest.fn();
    render( <SomeComponent value="this is some content" onChange={onChange} /> );

    await waitFor( () => expect( screen.getByText( /some content/ ) ).toBeTruthy() );

    await userEvent.click( document.querySelector( '[contenteditable="true"]' ) );

    userEvent.keyboard( 'more stuff' );

    await waitFor( () => expect( onChange ).toHaveBeenCalled() );
} );

The mocks presented above only test two basic scenarios, and more will likely need to be added, which may change with each version of the editor.

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