Draft.js

Common errors

• Cannot read properties of undefined (reading 'focus')

  cause Attempting to call `editor.focus()` before the editor component's ref is properly assigned or when the component is unmounted.
  fix Ensure the ref (`editorRef.current` in Hooks or `this.editor` in classes) is checked for null/undefined before calling `focus()`. Use `React.useEffect` with an empty dependency array for initial focus or conditional rendering.

• The Draft.js editor is blank/empty/not visible, even though it's rendered.

  cause The essential `draft-js/dist/Draft.css` stylesheet is not loaded, resulting in missing default styles for block positioning, alignment, and cursor behavior.
  fix Add `import 'draft-js/dist/Draft.css';` to your application's entry file or the component where the Draft.js Editor is used.

• Editor state or selection becomes inconsistent or unresponsive after user input.

  cause This often happens with asynchronous updates to React state, leading to race conditions where the editor's internal state doesn't match the DOM, or external DOM manipulation by browser extensions.
  fix Ensure `EditorState` updates are immediate and synchronous when passed to the `Editor` component. Avoid external DOM modifications within the `contentEditable` area. Consider using `EditorState.push` for controlled changes.

• Module not found: Error: Can't resolve 'draft-js-export-html'

  cause Attempting to use utility functions (like converting `ContentState` to HTML or Markdown) from external packages without installing them.
  fix Install the necessary conversion library (e.g., `draft-js-export-html`, `draft-js-import-html`) using `npm install <package-name>` or `yarn add <package-name>`.

Warnings

• breaking The Entity storage API was changed significantly between v0.10.0 and v0.11.0. While v0.10.x supported both old and new APIs, v0.11.0 removed the old API entirely. Projects upgrading from versions prior to 0.10.0 must migrate their entity handling.
  Fix: Review the official Draft.js documentation on Entity API changes and update your `Entity` creation and management logic to use the new API structure.
• gotcha Draft.js is no longer actively maintained. The project's GitHub repository was archived in February 2023 and the last release was in August 2020. This means there will be no further bug fixes, security patches, or feature development. Consider alternatives for new projects or plan for in-house maintenance for existing ones.
  Fix: For new projects, evaluate actively maintained alternatives like Lexical or Slate. For existing projects, understand the risks of using abandoned software and prepare to fork or migrate if critical issues arise.
• gotcha Draft.js relies heavily on `immutable-js` for its data model. This introduces an additional dependency and a functional programming paradigm that can have a steep learning curve for developers unfamiliar with immutable data structures. Performance can also be a concern with very large documents.
  Fix: Familiarize yourself with `immutable-js` concepts. For performance-critical applications with extensive content, profile editor behavior and consider optimizing custom components or exploring alternatives.
• gotcha The editor requires `draft-js/dist/Draft.css` to be included for basic styling. Without it, the editor might appear as a blank input field, have incorrect cursor positioning, or display blocks improperly.
  Fix: Ensure `import 'draft-js/dist/Draft.css';` (or equivalent CSS import) is present in your application's entry point or the component where the editor is used.
• gotcha Draft.js can experience issues with delayed state updates or modifications to the DOM by browser extensions/plugins. The editor expects immediate updates and renders, and delays can cause a disconnect between keystrokes and editor state, leading to broken selection or input.
  Fix: Avoid batching or delaying `EditorState` updates that are directly propagated to the `Editor` component. Ensure `EditorState` always updates immediately. Be aware that browser extensions can interfere, which is often beyond direct code control.

Install

• npm install draft-js npm
• yarn add draft-js yarn
• pnpm add draft-js pnpm

Imports

• Editor
  wrong:

  const Editor = require('draft-js').Editor;

  correct:

  import { Editor } from 'draft-js';

  CommonJS `require` syntax is often incorrect in modern React projects that are typically ESM-first. Ensure your bundler handles it correctly.
• EditorState
  wrong:

  import EditorState from 'draft-js/lib/EditorState';

  correct:

  import { EditorState } from 'draft-js';

  Importing directly from `lib/` paths is generally discouraged as it's an internal implementation detail and can break between versions.
• Modifier
  wrong:

  import { EditorState, Modifier } from 'draft-js/lib/DraftModifier';

  correct:

  import { Modifier } from 'draft-js';

  Provides methods for applying changes to `ContentState`. Prefer named imports from the main package entry point.
• RichUtils
  wrong:

  const RichUtils = require('draft-js/lib/RichUtils');

  correct:

  import { RichUtils } from 'draft-js';

  Offers convenience methods for common rich text operations like bold, italic, and block type changes.

Quickstart

This example demonstrates a basic Draft.js editor using React Hooks, including state management, focusing, and handling basic key commands like bold/italic via RichUtils.

import React from 'react';
import ReactDOM from 'react-dom';
import { Editor, EditorState, RichUtils } from 'draft-js';
import 'draft-js/dist/Draft.css'; // Essential for basic styling

function MyEditor() {
  const [editorState, setEditorState] = React.useState(
    EditorState.createEmpty()
  );

  const editorRef = React.useRef(null);

  const focusEditor = () => {
    if (editorRef.current) {
      editorRef.current.focus();
    }
  };

  React.useEffect(() => {
    focusEditor();
  }, []);

  const handleKeyCommand = (command, editorState) => {
    const newState = RichUtils.handleKeyCommand(editorState, command);
    if (newState) {
      setEditorState(newState);
      return 'handled';
    }
    return 'not-handled';
  };

  return (
    <div style={{ border: '1px solid gray', minHeight: '6em', padding: '10px' }} onClick={focusEditor}>
      <Editor
        ref={editorRef}
        editorState={editorState}
        onChange={setEditorState}
        handleKeyCommand={handleKeyCommand}
        placeholder="Tell a story..."
      />
    </div>
  );
}

const container = document.getElementById('container');
if (container) {
  ReactDOM.render(<MyEditor />, container);
} else {
  console.warn("Element with ID 'container' not found. Quickstart code won't render.");
}