This document provides an overview of the basics of the
Draft API. A
is also available to follow along.
Editor React component is built as a controlled ContentEditable component,
with the goal of providing a top-level API modeled on the familiar React
controlled input API.
As a brief refresher, controlled inputs involve two key pieces:
- A value to represent the state of the input
- An onChange prop function to receive updates to the input
This approach allows the component that composes the input to have strict control over the state of the input, while still allowing updates to the DOM to provide information about the text that the user has written.
The top-level component can maintain control over the input state via this
value state property.
Controlling Rich Text
In a React rich text scenario, however, there are two clear problems:
- A string of plaintext is insufficient to represent the complex state of a rich editor.
- There is no such
onChangeevent available for a ContentEditable element.
State is therefore represented as a single immutable
EditorState object, and
implemented within the
Editor core to provide this state value to the top
EditorState object is a complete snapshot of the state of the editor,
including contents, cursor, and undo/redo history. All changes to content and
selection within the editor will create new
EditorState objects. Note that
this remains efficient due to data persistence across immutable objects.
For any edits or selection changes that occur in the editor DOM, your
handler will execute with the latest
EditorState object based on those