This article discusses the Entity system, which Draft uses for annotating ranges of text with metadata. Entities introduce levels of richness beyond styled text. Links, mentions, and embedded content can all be implemented using entities.
The Entity API Reference provides details on the static methods to be used when creating, retrieving, or updating entity objects.
For information about recent changes to the Entity API, and examples of how to update your application, see our v0.10 API Migration Guide.
An entity is an object that represents metadata for a range of text within a Draft editor. It has three properties:
- type: A string that indicates what kind of entity it is, e.g.
- mutability: Not to be confused with immutability a la
immutable-js, this property denotes the behavior of a range of text annotated with this entity object when editing the text range within the editor. This is addressed in greater detail below.
- data: An optional object containing metadata for the entity. For instance,
'LINK'entity might contain a
dataobject that contains the
hrefvalue for that link.
All entities are stored in the ContentState record. The entities are referenced
by key within
ContentState and React components used to decorate annotated
ranges. (We are currently deprecating a previous API for accessing Entities; see
Creating and Retrieving Entities
Entities should be created using
contentState.createEntity, which accepts the
three properties above as arguments. This method returns a
ContentState record updated to include the newly created entity, then you can call
contentState.getLastCreatedEntityKey to get the key of the newly created entity record.
This key is the value that should be used when applying entities to your
content. For instance, the
Modifier module contains an
For a given range of text, then, you can extract its associated entity key by using
getEntityAt() method on a
ContentBlock object, passing in the target
Entities may have one of three "mutability" values. The difference between them is the way they behave when the user makes edits to them.
DraftEntityInstance objects are always immutable Records, and this
property is meant only to indicate how the annotated text may be "mutated" within
the editor. (Future changes may rename this property to ward off potential
confusion around naming.)
This text cannot be altered without removing the entity annotation from the text. Entities with this mutability type are effectively atomic.
For instance, in a Facebook input, add a mention for a Page (e.g. Barack Obama). Then, either add a character within the mentioned text, or try to delete a character. Note that when adding or deleting characters, the entity is removed.
This mutability value is useful in cases where the text absolutely must match its relevant metadata, and may not be altered.
This text may be altered freely. For instance, link text is generally intended to be "mutable" since the href and linkified text are not tightly coupled.
Entities that are "segmented" are tightly coupled to their text in much the same way as "immutable" entities, but allow customization via deletion.
For instance, in a Facebook input, add a mention for a friend. Then, add a character to the text. Note that the entity is removed from the entire string, since your mentioned friend may not have their name altered in your text.
Next, try deleting a character or word within the mention. Note that only the section of the mention that you have deleted is removed. In this way, we can allow short names for mentions.
DraftEntityInstance records are immutable, you may not update the
property on an instance directly.
Entity methods are available to modify entities:
replaceData. The former allows updating data by passing in an object to merge,
while the latter completely swaps in the new data object.
Using Entities for Rich Content
The next article in this section covers the usage of decorator objects, which can be used to retrieve entities for rendering purposes.
The link editor example provides a working example of entity creation and decoration in use.