Skip to content
Portable Text Editor

Behavior API Overview

Reference docs for the behavior API.

defineBehavior

Options Object

  • on (string): Internal editor event
  • guard (function or boolean): function accepts snapshot and event, returns boolean
  • actions (array): function accepts snapshot and event, returns array of actions

Example

const noLowerCaseA = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [({snapshot, event}) => [{type: 'insert.text', text: 'A'}]],
})

Behavior Event types

Native event types

  • clipboard.copy
  • clipboard.cut
  • clipboard.paste
  • drag.dragstart
  • drag.drag
  • drag.dragend
  • drag.dragenter
  • drag.dragover
  • drag.drop
  • drag.dragleave
  • keyboard.keydown
  • keyboard.keyup
  • mouse.click

Synthetic event types

  • annotation.add
  • annotation.remove
  • annotation.toggle
  • block.set
  • block.unset
  • decorator.add
  • decorator.remove
  • decorator.toggle
  • delete.backward
  • delete.block
  • delete.forward
  • delete.text
  • deserialization.failure
  • deserialization.success
  • deserialize
  • insert.block
  • insert.blocks
  • insert.break
  • insert.inline object
  • insert.soft break
  • insert.span
  • insert.text
  • list item.add
  • list item.remove
  • list item.toggle
  • move.block
  • move.block down
  • move.block up
  • select
  • select.next block
  • select.previous block
  • serialization.failure
  • serialization.success
  • serialize
  • split
  • style.add
  • style.remove
  • style.toggle

Custom event types

  • custom.* (e.g. custom.add link)

Behavior Actions

execute

The execute action type is used to execute events to resolution.

Properties:

  • type: execute
  • event: Native event object
const executedUppercaseA = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [
    ({snapshot, event}) => [
      {type: 'execute', event: {type: 'insert.text', text: 'A'}},
    ],
  ],
})

When an event is executed, no other Behavior will be triggered.

The execute action also has a handy shorthand function:

const executedUppercaseA = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [({snapshot, event}) => [execute({type: 'insert.text', text: 'A'})]],
})

forward

The forward action type is used to forward events to the next Behavior.

Properties:

  • type: forward
  • event: Behavior event object
const forwardedUppercaseA = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [({snapshot, event}) => [{type: 'forward', event: {type: 'insert.text', text: 'A'}})]],
})

When an event is forwarded, the next Behavior will be triggered.

The forward action also has a handy shorthand function:

const forwardedUppercaseA = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [({snapshot, event}) => [forward({type: 'insert.text', text: 'A'})]],
})

raise

The raise action type is used to sends events back into the editor.

Properties:

  • type: raise
  • event: Behavior event object
const raisedUppercaseA = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [
    ({snapshot, event}) => [
      {type: 'raise', event: {type: 'insert.text', text: 'A'}},
    ],
  ],
})

The raise action also has a handy shorthand function:

const raisedUppercaseA = defineBehavior({
  on: 'insert.text',
  guard: ({snapshot, event}) => event.text === 'a',
  actions: [({snapshot, event}) => [raise({type: 'insert.text', text: 'A'})]],
})