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.
defineBehavior
Section titled “defineBehavior”Options Object
- on (string): Internal editor event
- guard (function or boolean): function accepts
snapshot,event, anddom, 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 elementdom.getBlockNodes(snapshot)anddom.getChildNodes(snapshot): the DOM nodes of the blocks and the children in the selectiondom.getStartBlockElement(snapshot)anddom.getEndBlockElement(snapshot): the elements of the first and last block in the selectiondom.getSelectionRect(snapshot): the bounding rect of the selectiondom.getPointAtCoordinates({x, y}): the editor point where a click at the viewport coordinates would place the caretdom.setDragGhost({event, ghost}): sets the drag image for adrag.dragstartevent
Example
Section titled “Example”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'}}, ], ],})Behavior event types
Section titled “Behavior event types”Native event types
Section titled “Native event types”- 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
Synthetic event types
Section titled “Synthetic event types”- 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 event types
Section titled “Custom event types”- custom.* (e.g. custom.add link)
Behavior actions
Section titled “Behavior actions”execute
Section titled “execute”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'})]],})forward
Section titled “forward”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'})]],})