DraftJS Utils

Common errors

• TypeError: block.getText is not a function

  cause Attempting to call Immutable.js `ContentBlock` methods on a plain JavaScript object or an incorrectly typed block.
  fix Ensure that the `block` variable is a valid `ContentBlock` instance returned by a `draftjs-utils` function, which are typically Immutable.js objects. Access methods using `block.get('text')` or ensure correct typing.

• TypeError: Cannot read properties of undefined (reading 'getSelection')

  cause Passing `null` or `undefined` instead of a valid `EditorState` instance to a `draftjs-utils` function.
  fix Always pass a properly initialized `EditorState` object to `draftjs-utils` functions. Verify that your `editorState` variable is not `null` or `undefined`.

• TypeError: Immutable.List.prototype.get not defined

  cause This error or similar (e.g., for `OrderedMap`) indicates that you are trying to use an Immutable.js method on an object that is not an Immutable.js collection, possibly due to `immutable` version mismatch or incorrect usage.
  fix Verify that your `immutable` package version is compatible with both `draft-js` and `draftjs-utils`. Ensure the object you are calling `.get()` on is indeed an `Immutable.List` or `Immutable.OrderedMap` as expected by the utility's return type.

Warnings

• gotcha Many utility functions return Immutable.js data structures (e.g., `Immutable.List`, `Immutable.OrderedMap`), not plain JavaScript arrays or objects. Direct access via `[index]` or `.property` will fail; instead, use Immutable.js methods like `.get(index)` or `.map()`, `.forEach()`, etc.
  Fix: Familiarize yourself with Immutable.js API methods for collections. Always check the return type documentation for each utility function.
• gotcha The peer dependency for `immutable` allows both `3.x.x` and `4.x.x`. `draft-js` itself often has a more specific `immutable` dependency. Mismatches between your `draft-js` and `draftjs-utils`'s effective `immutable` version can lead to subtle bugs or runtime errors due to different Immutable.js API behaviors or data structures.
  Fix: Ensure that your `immutable` installation aligns with the exact version required by your `draft-js` package. Use `npm ls immutable` or `yarn why immutable` to inspect the resolved version.
• breaking As a pre-1.0 library (currently at 0.10.x), minor version increments (e.g., from 0.10.x to 0.11.x) may introduce breaking changes without adhering strictly to semantic versioning's major version bump rule. Always review the changelog when upgrading.
  Fix: Consult the package's GitHub releases or `CHANGELOG.md` for specific breaking changes and migration instructions before upgrading pre-1.0 versions.

Install

• npm install draftjs-utils npm
• yarn add draftjs-utils yarn
• pnpm add draftjs-utils pnpm

Imports

• getSelectedBlocksList
  wrong:

  const { getSelectedBlocksList } = require('draftjs-utils');

  correct:

  import { getSelectedBlocksList } from 'draftjs-utils';

  Primary usage is via named ESM imports. CommonJS `require` works but is less idiomatic in modern React/Draft.js projects.
• getSelectionText
  wrong:

  import getSelectionText from 'draftjs-utils';

  correct:

  import { getSelectionText } from 'draftjs-utils';

  All utilities are named exports; there is no default export from the package.
• removeSelectedBlocksStyle
  wrong:

  import * as DraftUtils from 'draftjs-utils'; DraftUtils.removeSelectedBlocksStyle(...);

  correct:

  import { removeSelectedBlocksStyle } from 'draftjs-utils';

  While star imports technically work, it's generally better practice to directly import the specific utilities you need for better tree-shaking.

Quickstart

Demonstrates how to initialize an `EditorState` and use `draftjs-utils` to retrieve selected blocks and text, and apply a basic modification, highlighting the Immutable.js returns.

import { EditorState, ContentState, SelectionState } from 'draft-js';
import { getSelectedBlocksList, getSelectionText, removeSelectedBlocksStyle } from 'draftjs-utils';

// Create a basic EditorState for demonstration purposes.
// In a real application, EditorState would come from your Draft.js editor component.
const contentState = ContentState.createFromText('Hello world! This is a test paragraph.');
const selectionState = SelectionState.createEmpty(contentState.getFirstBlock().getKey())
  .merge({
    anchorKey: contentState.getFirstBlock().getKey(),
    anchorOffset: 6,
    focusKey: contentState.getFirstBlock().getKey(),
    focusOffset: 11,
    isBackward: false,
    hasFocus: true
  });
const editorState = EditorState.forceSelection(EditorState.createWithContent(contentState), selectionState);

console.log('--- Using draftjs-utils ---');

// 1. Get selected blocks as an Immutable.List
const selectedBlocks = getSelectedBlocksList(editorState);
console.log('Selected Blocks Count:', selectedBlocks.size);
selectedBlocks.forEach((block, index) => {
  console.log(`Block ${index + 1} Text: "${block.getText()}"`);
});

// 2. Get selected text as a plain string
const selectedText = getSelectionText(editorState);
console.log('Selected Text:', `"${selectedText}"`);

// 3. Example of a modification utility: remove style from selected blocks
// This returns a new EditorState which you would then set in your Draft.js editor.
const newEditorState = removeSelectedBlocksStyle(editorState);
console.log('EditorState modified?', newEditorState !== editorState);