Create a custom behavior

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

For a deep dive into behaviors and how they work, check out Behaviors.

Import the behavior helper

Begin by importing defineBehavior.

import {defineBehavior} from '@portabletext/editor'

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 Behaviors Learn more about how each part of the Behavior API works.

Register the behavior

In order 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>