v0.10 API Migration

The Draft.js v0.10 release includes a change to the API for managing DraftEntity data; the global 'DraftEntity' module is being deprecated and DraftEntity instances will be managed as part of ContentState. This means that the methods which were previously accessed on DraftEntity are now moved to the ContentState record.

The global API was deprecated in v0.10, but v0.11 retained both APIs. Removal was planned for v0.12; it was not a completed migration in the archived v0.11 release line. See the maintainer’s migration status update. Use the ContentState methods below for new code.

The planned migration aimed to make entity storage immutable, remove global access, and make entity-data changes trigger a re-render. Using the ContentState API in v0.11 does not by itself guarantee those implementation changes.

Quick Overview

Here is a quick list of what has been changed and how to update your application:

Creating an Entity

Old Syntax

const entityKey = Entity.create(urlType, "IMMUTABLE", { src: urlValue })

New Syntax

const contentStateWithEntity = contentState.createEntity(urlType, "IMMUTABLE", {
  src: urlValue,
})
const entityKey = contentStateWithEntity.getLastCreatedEntityKey()

Getting an Entity

Old Syntax

const entityInstance = Entity.get(entityKey)
// entityKey is a string key associated with that entity when it was created

New Syntax

const entityInstance = contentState.getEntity(entityKey)
// entityKey is a string key associated with that entity when it was created

Decorator strategy arguments change

Old Syntax

const compositeDecorator = new CompositeDecorator([
  {
    strategy: (contentBlock, callback) =>
      exampleFindTextRange(contentBlock, callback),
    component: ExampleTokenComponent,
  },
])

New Syntax

const compositeDecorator = new CompositeDecorator([
  {
    strategy: (contentBlock, callback, contentState) => (
      contentBlock,
      callback,
      contentState
    ),
    component: ExampleTokenComponent,
  },
])

Note that ExampleTokenComponent will receive contentState as a prop.

Why does the 'contentState' get passed into the decorator strategy now? Because we may need it if our strategy is to find certain entities in the contentBlock:

const mutableEntityStrategy = function (contentBlock, callback, contentState) {
  contentBlock.findEntityRanges((character) => {
    const entityKey = character.getEntity()
    if (entityKey === null) {
      return false
    }
    // To look for certain types of entities,
    // or entities with a certain mutability,
    // you may need to get the entity from contentState.
    // In this example we get only mutable entities.
    return contentState.getEntity(entityKey).getMutability() === "MUTABLE"
  }, callback)
}

Decorator Strategies that find Entities

Old Syntax

function findLinkEntities(contentBlock, callback) {
  contentBlock.findEntityRanges((character) => {
    const entityKey = character.getEntity()
    return entityKey !== null && Entity.get(entityKey).getType() === "LINK"
  }, callback)
}

New Syntax

function findLinkEntities(contentBlock, callback, contentState) {
  contentBlock.findEntityRanges((character) => {
    const entityKey = character.getEntity()
    return (
      entityKey !== null &&
      contentState.getEntity(entityKey).getType() === "LINK"
    )
  }, callback)
}

More Information

See the updated examples.