Create a custom behavior

Behaviors add functionality to the Portable Text Editor (PTE) in a declarative way.

To learn how behaviors work, read Behaviors.

Import the behavior helper

Begin by importing defineBehavior.

import {defineBehavior} from '@portabletext/editor/behaviors'

Define the behavior

Behaviors need three things:

• A triggering event. See the full list of events.
• A guard, or condition that determines if this behavior should apply.
• An action to invoke if the event and guard are met.

Here’s an example behavior:

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

Let’s break it down:

1. It listens for the insert.text event. You can use any native, synthetic or custom event here.
2. The guard checks if the text that triggered this event is equal to a lowercase a. The guard is true and the behavior will perform the actions.
3. It sends an execute action with an insert.text event to insert “A” instead of “a”.

Understanding BehaviorsLearn more about how each part of the Behavior API works.

Register the behavior

To use the behavior, add it to the EditorProvider using the BehaviorPlugin.

import {defineBehavior} from '@portabletext/editor/behaviors'
import {BehaviorPlugin} from '@portabletext/editor/plugins'

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

// ...

<EditorProvider
    initialConfig={{
        schemaDefinition,
    }}
>
    <BehaviorPlugin behaviors={[noLowerCaseA]} />
    {/* ... */}
</EditorProvider>