Skip to content
This page is available as Markdown at /editor/reference/behavior-api.md. For the full documentation index, see /llms.txt, or the complete corpus at /llms-full.txt.

Behavior API overview

Reference docs for the behavior API.

Options Object

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

The dom parameter provides access to the editor’s rendered DOM:

  • dom.getEditorElement(): the editor’s root element
  • dom.getBlockNodes(snapshot) and dom.getChildNodes(snapshot): the DOM nodes of the blocks and the children in the selection
  • dom.getStartBlockElement(snapshot) and dom.getEndBlockElement(snapshot): the elements of the first and last block in the selection
  • dom.getSelectionRect(snapshot): the bounding rect of the selection
  • dom.getPointAtCoordinates({x, y}): the editor point where a click at the viewport coordinates would place the caret
  • dom.setDragGhost({event, ghost}): sets the drag image for a drag.dragstart event
import {defineBehavior} from '@portabletext/editor/behaviors'
const noLowerCaseA = defineBehavior({
on: 'insert.text',
guard: ({snapshot, event}) => event.text === 'a',
actions: [
({snapshot, event}) => [
{type: 'execute', event: {type: 'insert.text', text: 'A'}},
],
],
})
  • clipboard.copy
  • clipboard.cut
  • clipboard.paste
  • drag.dragstart
  • drag.drag
  • drag.dragend
  • drag.dragenter
  • drag.dragover
  • drag.dragleave
  • drag.drop
  • input.*
  • keyboard.keydown
  • keyboard.keyup
  • mouse.click
  • annotation.add
  • annotation.remove
  • block.set
  • block.unset
  • child.set
  • child.unset
  • decorator.add
  • decorator.remove
  • delete
  • history.redo
  • history.undo
  • insert
  • insert.block
  • insert.child
  • insert.text
  • move.backward
  • move.forward
  • remove.text
  • select
  • set
  • unset
  • annotation.set
  • annotation.toggle
  • decorator.toggle
  • delete.backward
  • delete.block
  • delete.child
  • delete.forward
  • delete.text
  • deserialize
  • deserialize.data
  • deserialization.success
  • deserialization.failure
  • insert.blocks
  • insert.break
  • insert.inline object
  • insert.soft break
  • insert.span
  • list item.add
  • list item.remove
  • list item.toggle
  • move.block
  • move.block down
  • move.block up
  • select.block
  • select.previous block
  • select.next block
  • serialize
  • serialize.data
  • serialization.success
  • serialization.failure
  • split
  • style.add
  • style.remove
  • style.toggle
  • custom.* (e.g. custom.add link)

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

Properties:

  • type: execute
  • event: Synthetic event object
import {defineBehavior} from '@portabletext/editor/behaviors'
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:

import {defineBehavior, execute} from '@portabletext/editor/behaviors'
const executedUppercaseA = defineBehavior({
on: 'insert.text',
guard: ({snapshot, event}) => event.text === 'a',
actions: [({snapshot, event}) => [execute({type: 'insert.text', text: 'A'})]],
})

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

Properties:

  • type: forward
  • event: Behavior event object
import {defineBehavior} from '@portabletext/editor/behaviors'
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:

import {defineBehavior, forward} from '@portabletext/editor/behaviors'
const forwardedUppercaseA = defineBehavior({
on: 'insert.text',
guard: ({snapshot, event}) => event.text === 'a',
actions: [({snapshot, event}) => [forward({type: 'insert.text', text: 'A'})]],
})

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

Properties:

  • type: raise
  • event: Behavior event object
import {defineBehavior} from '@portabletext/editor/behaviors'
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:

import {defineBehavior, raise} from '@portabletext/editor/behaviors'
const raisedUppercaseA = defineBehavior({
on: 'insert.text',
guard: ({snapshot, event}) => event.text === 'a',
actions: [({snapshot, event}) => [raise({type: 'insert.text', text: 'A'})]],
})