React rich text multi-root editor hook

This page focuses on describing the usage of the multi-root editor in React applications. If you would like to use a different type of editor, you can find more information here.

The easiest way to use multi-root CKEditor 5 in your React application is by using the multi-root rich text editor build.

# Quick start

This guide assumes you already have a React project. If you want to create a new one, you can use the create-react-app CLI. It allows you to create and customize your project with templates. For example, you can set up your project with TypeScript support.

Install the CKEditor 5 WYSIWYG editor package for React and the multi-root editor build. Assuming that you picked @ckeditor/ckeditor5-build-multi-root:

npm install --save @ckeditor/ckeditor5-react @ckeditor/ckeditor5-build-multi-root

Use the useMultiRootEditor hook inside your project:

// App.jsx / App.tsx

import React from 'react';
import { useMultiRootEditor } from '@ckeditor/ckeditor5-react';
import MultiRootEditor from '@ckeditor/ckeditor5-build-multi-root';

const App = () => {
    const editorProps = {
        editor: MultiRootEditor,
        data: {
            intro: '<h1>React multi-root editor</h1>',
            content: '<p>Hello from CKEditor&nbsp;5 multi-root!</p>'
        },
        config: {
            // your editor config
        }
    };

    const {
        editor, toolbarElement, editableElements,
        data, setData,
        attributes, setAttributes
    } = useMultiRootEditor( editorProps );

    return (
        <div className="App">
            <h2>Using CKEditor&nbsp;5 multi-root build in React</h2>

            { toolbarElement }

            { editableElements }
        </div>
    );
}

export default App;

# Hook properties

The useMultiRootEditor hook supports the following properties:

• editor: MultiRootEditor (required) – The MultiRootEditor constructor to use.
• data: Object – The initial data for the created editor. See the Getting and setting data guide.
• rootsAttributes: Object – The initial roots attributes for the created editor.
• config: Object – The editor configuration. See the Configuration guide.
• disabled: Boolean – The MultiRootEditor is being switched to read-only mode if the property is set to true.
• disableWatchdog: Boolean – If set to true, the watchdog feature will be disabled. It is set to false by default.
• watchdogConfig: WatchdogConfig – Configuration object for the watchdog feature.
• isLayoutReady: Boolean – A property that delays the editor creation when set to false. It starts the initialization of the multi-root editor when sets to true. Useful when the CKEditor 5 annotations or a presence list are used.
• disableTwoWayDataBinding: Boolean – Allows disabling the two-way data binding mechanism between the editor state and data object to improve editor efficiency. The default value is false.
• onReady: Function – It is called when the editor is ready with a MultiRootEditor instance. This callback is also called after the reinitialization of the component if an error occurred.
• onChange: Function – It is called when the editor data has changed. See the editor.model.document#change:data event.
• onBlur: Function – It is called when the editor was blurred. See the editor.editing.view.document#blur event.
• onFocus: Function – It is called when the editor was focused. See the editor.editing.view.document#focus event.
• onError: Function – It is 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:
  • phase: 'initialization'|'runtime' – Informs when the error has occurred (during the editor or context initialization, or after the initialization).
  • willEditorRestart: Boolean – 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 MultiRootEditor instance.

# Hook values

The useMultiRootEditor hook returns the following values:

• editor – The instance of created editor.
• toolbarElement – ReactElement that contains the toolbar. It could be rendered anywhere in the application.
• editableElements – An array of ReactElements that describes the editor’s roots. This array is updated after detaching an existing root or adding a new root.
• data – The current state of the editor’s data. It is updated after each editor update. Note that you should not use it if you disabled two-way binding by passing the disableTwoWayDataBinding property.
• setData – The function used for updating the editor’s data.
• attributes – The current state of the editor’s attributes. It is updated after each editor attributes update. Note that you should not use it if you disabled two-way binding by passing the disableTwoWayDataBinding property.
• setAttributes – The function used for updating the editor’s attributes.

# Context feature

The useMultiRootEditor hook also supports the context feature, as described in the main React integration guide.

However, as the multi-root editor addresses most use cases of the context feature, consider if you need to employ it.

# Two-way data binding

By default, the two-way data binding is enabled. It means that every change done in the editor is automatically applied in the data object returned from the useMultiRootEditor hook. Additionally, if you want to change or set data in the editor, you can simply use setData method provided by the hook. It works the same way in case of attributes – the hook provides the attributes object and the setAttributes method to update them. It ensures that if you want to use or save the state of the editor, these objects are always up-to-date.

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