Entity is a static module containing the API for creating, retrieving, and
updating entity objects, which are used for annotating text ranges with metadata.
This module also houses the single store used to maintain entity data.
This article is dedicated to covering the details of the API. See the advanced topics article on entities for more detail on how entities may be used.
Please note that the API for entity storage and management has changed recently; for details on updating your application see our v0.10 API Migration Guide.
Entity objects returned by
Entity methods are represented as
DraftEntityInstance immutable records. These have a small set of getter functions and should
be used only for retrieval.
- create(...): DraftEntityInstance
- add(instance: DraftEntityInstance): string
- get(key: string): DraftEntityInstance
- mergeData(...): DraftEntityInstance
- replaceData(...): DraftEntityInstance
create (Deprecated in favour of
create method should be used to generate a new entity object with the
Note that a string is returned from this function. This is because entities
are referenced by their string key in
ContentState. The string value should
be used within
CharacterMetadata objects to track the entity for annotated
add (Deprecated in favour of
In most cases, you will use
Entity.create(). This is a convenience method
that you probably will not need in typical Draft usage.
add function is useful in cases where the instances have already been
created, and now need to be added to the
Entity store. This may occur in cases
ContentState is being revived
get (Deprecated in favour of
DraftEntityInstance for the specified key. Throws if no instance
exists for that key.
mergeData (Deprecated in favour of
DraftEntityInstance objects are immutable, you cannot update an entity's
metadata through typical mutative means.
mergeData method allows you to apply updates to the specified entity.
replaceData (Deprecated in favour of
replaceData method is similar to the
mergeData method, except it will
totally discard the existing
data value for the instance and replace it with