Plugins

Plugins can be attached to an editor to alter its behavior in different ways. Plugins are just simple Javascript objects, containing a set of properties that control different behaviors—event handling, change handling, rendering, etc.

Each editor has a "middleware stack" of plugins, which has a specific order.

When the editor needs to resolve a plugin-related handler, it will loop through its plugin stack, searching for the first plugin that successfully returns a value. After receiving that value, the editor will not continue to search the remaining plugins; it returns early. If you'd like for the stack to continue, a plugin handler should return undefined.

Conventions

A plugin should always export a function that takes options. This way even if it doesn't take any options now, it won't be a breaking API change to take more options in the future. So a basic plugin might look like this:

export default function MySlatePlugin(options) {
  return {
    // Return properties that describe your logic here...
  }
}

Event Handler Properties

{
  onBeforeInput: Function,
  onBlur: Function,
  onFocus: Function,
  onCopy: Function,
  onCut: Function,
  onDrop: Function,
  onKeyDown: Function,
  onKeyUp: Function,
  onPaste: Function,
  onSelect: Function
}

All of the event handler properties are passed the same React event object you are used to from React's event handlers. They are also passed a change object representing any changes that have resulted from the event, and the editor instance itself.

Each event handler can choose to call methods on the change object, in which case the editor's value will be updated.

If the return value of a plugin handler is null, the editor will simply continue resolving the plugin stack. However, if you return a non-null value, the editor will break out of the loop.

onBeforeInput

Function onBeforeInput(event: Event, change: Change, editor: Editor) => Change || Void

This handler is called right before a string of text is inserted into the contenteditable element.

Make sure to event.preventDefault() if you do not want the default insertion behavior to occur!

onBlur

Function onBlur(event: Event, change: Change, editor: Editor) => Change || Void

This handler is called when the editor's contenteditable element is blurred.

onFocus

Function onFocus(event: Event, change: Change, editor: Editor) => Change || Void

This handler is called when the editor's contenteditable element is focused.

onCopy

Function onCopy(event: Event, change: Change, editor: Editor) => Change || Void

This handler is called when there is a copy event in the editor's contenteditable element.

onCut

Function onCut(event: Event, change: Change, editor: Editor) => Change || Void

This handler is equivalent to the onCopy handler.

onDrop

Function onDrop(event: Event, change: Change, editor: Editor) => Change || Void

This handler is called when the user drops content into the contenteditable element. The event is already prevented by default, so you must define a value change to have any affect occur.

onKeyDown

Function onKeyDown(event: Event, change: Change, editor: Editor) => Change || Void

This handler is called when any key is pressed in the contenteditable element, before any action is taken.

Make sure to event.preventDefault() if you do not want the default insertion behavior to occur!

onKeyUp

Function onKeyUp(event: Event, change: Change, editor: Editor) => Change || Void

This handler is called when any key is released in the contenteditable element.

onPaste

Function onPaste(event: Event, change: Change, editor: Editor) => Change || Void

This handler is called when the user pastes content into the contenteditable element. The event is already prevented by default, so you must define a value change to have any affect occur.

onSelect

Function onSelect(event: Event, change: Change, editor: Editor) => Change || Void

This handler is called whenever the native DOM selection changes.

Note: This is not Slate's internal selection representation (although it mirrors it). If you want to get notified when Slate's selection changes, use the onChange property of the <Editor>. This handler is instead meant to give you lower-level access to the DOM selection handling, which is not always triggered as you'd expect.

Slate-React Properties

{
  onChange: Function,
  shouldNodeComponentUpdate: Function
}

onChange

Function onChange(change: Change, editor: Editor) => Any || Void

The onChange handler isn't a native browser event handler. Instead, it is invoked whenever the editor value changes. This allows plugins to augment a change however they want.

shouldNodeComponentUpdate

Function shouldNodeComponentUpdate(previousEditorProps: Object, editorProps: Object) => true || Void

If this function returns true, it can force updating the editor where otherwise it wouldn't.

Slate-React Rendering

{
  renderEditor: Function,
  renderMark: Function,
  renderNode: Function,
  renderPlaceholder: Function,
}

These renderProps are used to create the Editor UI. They are called for each plugin in reverse plugin order (so the last plugin in the array is called first) and results are passed on as children to the next plugin.

renderEditor

Function renderEditor(props: Object, editor: Editor) => ReactNode || Void

The renderEditor property allows you to define higher-order-component-like behavior. It is passed all of the properties of the editor, including props.children. You can then choose to wrap the existing children in any custom elements or proxy the properties however you choose. This can be useful for rendering toolbars, styling the editor, rendering validation, etc. Remember that the renderEditor function has to render props.children for editor's children to render.

renderMark

Function renderMark({ editor, mark, marks, node, offset, text, children, attributes }) => ReactNode || Void

Render a Mark.

renderNode

Function renderNode({ key, editor, isFocused, isSelected, node, parent, readOnly, children, attributes }) => ReactNode || Void

Render a Node.

renderPlaceholder

Function renderPlaceholder({ editor, mark, marks, node, offset, text, children, attributes }) => ReactNode || Void

Render the placeholder that is shown when the editor has no value.

The placeholder prop that was passed to the editor can be found at editor.props.placeholder.

Other Properties

{
  decorateNode: Function,
  normalizeNode: Function,
  schema: Object
}

decorateNode

Function decorateNode(node: Node) => [Range] || Void

normalizeNode

Function normalizeNode(node: Node) => Function(change: Change) || Void

schema

Object

The schema property allows you to define a set of rules that will be added to the editor's schema. The rules from each of the schemas returned by the plugins are collected into a single schema for the editor.