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 in this guide.
The multi-root editors in React are supported since version 6.2.0 of this package.
Unlike the default integration, we prepared the multi-root editor integration based on the hooks and new React mechanisms.
# Quick start
This guide assumes you already have a React project. If you want to create a new one, you can use the Vite 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 type.
npm install ckeditor5 @ckeditor/ckeditor5-react
Use the useMultiRootEditor
hook inside your project:
// App.jsx / App.tsx
import { MultiRootEditor, Bold, Essentials, Italic, Paragraph } from 'ckeditor5';
import { useMultiRootEditor } from '@ckeditor/ckeditor5-react';
import 'ckeditor5/ckeditor5.css';
const App = () => {
const editorProps = {
editor: MultiRootEditor,
data: {
intro: '<h1>React multi-root editor</h1>',
content: '<p>Hello from CKEditor 5 multi-root!</p>'
},
config: {
plugins: [ Essentials, Bold, Italic, Paragraph ],
toolbar: {
items: [ 'undo', 'redo', '|', 'bold', 'italic' ]
},
}
};
const {
editor,
toolbarElement,
editableElements,
data,
setData,
attributes,
setAttributes
} = useMultiRootEditor( editorProps );
return (
<div className="App">
<h2>Using CKEditor 5 multi-root editor in React</h2>
{ toolbarElement }
{ editableElements }
</div>
);
}
export default App;
# Hook properties
The useMultiRootEditor
hook supports the following properties:
editor: MultiRootEditor
(required) – TheMultiRootEditor
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
– TheMultiRootEditor
is being switched to read-only mode if the property is set totrue
.disableWatchdog: Boolean
– If set totrue
, the watchdog feature will be disabled. It is set tofalse
by default.watchdogConfig: WatchdogConfig
– Configuration object for the watchdog feature.isLayoutReady: Boolean
– A property that delays the editor creation when set tofalse
. It starts the initialization of the multi-root editor when sets totrue
. 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 anddata
object to improve editor efficiency. The default value isfalse
.onReady: Function
– It is called when the editor is ready with aMultiRootEditor
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 theeditor.model.document#change:data
event.onBlur: Function
– It is called when the editor was blurred. See theeditor.editing.view.document#blur
event.onFocus: Function
– It is called when the editor was focused. See theeditor.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 an error has occurred (during the editor or context initialization, or after the initialization).willEditorRestart: Boolean
– If set totrue
, the editor component will restart itself.
The editor event callbacks (onChange
, onBlur
, onFocus
) receive two arguments:
- An
EventInfo
object. - 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 ofReactElements
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 thedisableTwoWayDataBinding
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 thedisableTwoWayDataBinding
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.
Two-way data binding may lead to performance issues with large editor content. In such cases, it is recommended to disable it by setting the disableTwoWayDataBinding
property to true
when using the useMultiRootEditor
hook. When this is disabled, you will need to handle data synchronization manually if it is needed.
The recommended approach for achieving this is based on utilizing the autosave plugin. The second approach involves providing the onChange
callback, which is called on each editor update.
# How to?
# Using the editor with collaboration plugins
We provide several ready-to-use integration featuring collaborative editing with multi-root in React applications:
It is not necessary to build applications on top of the above samples, however, they should help you get started.
# 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.
Every day, we work hard to keep our documentation complete. Have you spotted outdated information? Is something missing? Please report it via our issue tracker.
With the release of version 42.0.0, we have rewritten much of our documentation to reflect the new import paths and features. We appreciate your feedback to help us ensure its accuracy and completeness.