Home/CKEditor 5/Getting startedReact 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.
Starting from version 6.0.0 of this package, you can use native type definitions provided by CKEditor 5. Check the details about TypeScript support.
CKEditor 5 BuilderIn our interactive Builder you can quickly get a taste of CKEditor 5. It 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 editor type.The features you need.Preferred framework (React, Angular, Vue or Vanilla JS).Preferred distribution method.At the end you get ready-to-use code tailored to your needs!
Check out our interactive Builder
# Quick start# Setting up the projectThis 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 npmFirst, 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-featuresThen, install the CKEditor 5 WYSIWYG editor component for React:
npm install @ckeditor/ckeditor5-reactUse the 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 ();}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 propertiesThe 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:
An EventInfo object.An Editor instance.# Context featureThe @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 ( {console.info( editors.editor1?.instance, editors.editor1?.yourAdditionalData );} }>{ // You can store the "editor" and use when it is needed. console.log( 'Editor 1 is ready to use!', editor );} } />{ // You can store the "editor" and use when it is needed. console.log( 'Editor 2 is ready to use!', editor );} } /> );}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.An example build that exposes both context and classic editor can be found in the CKEditor 5 collaboration sample.
# How to?# Using the document editor typeIf 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 ({ isMounted && ( {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() );}}}/>) });}export default App;# Using the editor with collaboration pluginsWe provide a few ready-to-use integrations featuring collaborative editing in React applications:
CKEditor 5 with real-time collaboration features and revision history featuresCKEditor 5 with offline comments, track changes and revision history featuresIt is not mandatory to build applications on top of the above samples, however, they should help you get started.
# LocalizationCKEditor 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 ();}export default App;For more information, please refer to the Setting the UI language guide.
# Jest testingJest 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:
VitestPlaywrightCypressThese 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 ( {editorRef.current = editor;} }data={ value }onChange={ () => {onChange( editorRef.current?.getData() );} }/>);};it( 'renders', async () => {render( );await waitFor( () => expect( screen.getByText( /some content/ ) ).toBeTruthy());} );it( 'updates', async () => {const onChange = jest.fn();render( );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 issuesThe 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.