> For the complete documentation index, see [llms.txt](/llms.txt).
> The full corpus is at [llms-full.txt](/llms-full.txt).

# Behavior API overview

> Reference documentation for the Behavior API.

import EventTypesList from '@/components/EventTypesList.astro'

Reference docs for the behavior API.

## `defineBehavior`

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 DOM-related utilities like `dom.findDOMNode()` for accessing the underlying DOM elements.

### Example

```tsx
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

### Native event types

<EventTypesList
  filePath="../../packages/editor/src/behaviors/behavior.types.event.ts"
  arrayName="nativeBehaviorEventTypes"
/>

### Synthetic event types

<EventTypesList
  filePath="../../packages/editor/src/behaviors/behavior.types.event.ts"
  arrayName="syntheticBehaviorEventTypes"
/>

<EventTypesList
  filePath="../../packages/editor/src/behaviors/behavior.types.event.ts"
  arrayName="abstractBehaviorEventTypes"
/>

### Custom event types

- custom.\* (e.g. custom.add link)

## Behavior actions

- [execute](#execute)
- [forward](#forward)
- [raise](#raise)
- effect

### `execute`

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

Properties:

- type: `execute`
- event: Native event object

```tsx
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:

```tsx
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

```tsx
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:

```tsx
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

```tsx
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:

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