> Lettrove docs 1.x · https://docs.lettrove.com/docs/editor/events

# Events

The editor tells your page what happens in it. Listen with `on` when you open it, so nothing is
missed while it loads, or with `editor.on()` afterwards.

```ts
const editor = await createEditor({
  // …
  on: {
    'design:saved': ({ designId, revision }) => saveToMyRecord(designId),
    error: ({ code, message }) => reportToMyLogs(code, message),
  },
});

const stop = editor.on('selection:changed', ({ blockId, type }) => showHelpFor(type));
stop(); // stops listening
```

In React, every event is a prop: `onReady`, `onDesignLoaded`, `onDesignUpdated`, `onDesignSaved`,
`onSelectionChanged`, `onImageUploaded`, `onConfigAdjusted`, `onThemeChanged`, `onError`.

Events are notifications: nothing waits for your listener, and a listener that throws does not
affect the editor. Payloads may gain fields within 1.x; ignore fields you do not know.

## The order of a session

```text
design:loaded   { designId: '01J9ZQ…', designVersion: 3 }
ready           { release: '1.0.0', protocol: 1, designVersion: 3 }   ← createEditor resolves here
selection:changed { blockId: 'hdg_k2x4q7m1', type: 'heading' }
design:updated  { design: {…}, revision: 1, change: { kind: 'edit', blockId: 'hdg_k2x4q7m1' } }
design:saved    { designId: '01J9ZQ…', revision: 2 }
…
```

## Every event

### `ready`
The editor is on screen and answers calls. `createEditor` resolves at the same moment.

| Field | |
|---|---|
| `release` | The editor release running, e.g. `1.0.0` |
| `protocol` | The protocol version the page and the editor agreed on |
| `designVersion` | The newest design format this editor reads |

### `design:loaded`
A design was opened, new or existing.

| Field | |
|---|---|
| `designId` | Its id |
| `designVersion` | The format it was stored in |
| `upgradedFrom` | Present when it was upgraded from an older format as it opened (it is saved in the new one; nothing is lost) |
| `hasNewerBlocks` | `true` when it holds blocks from a newer editor release, which are kept exactly as they are |

### `design:updated`
The design changed. A burst of edits is one event, so you can react to it without slowing typing
down.

| Field | |
|---|---|
| `design` | The whole design document, as it is on screen ([what you may rely on](/docs/api/design-document)) |
| `revision` | The saved revision the change is based on |
| `change.kind` | `edit`, `undo`, `redo`, `restore` (a restore point was put back) or `assistant` (the AI changed it) |
| `change.blockId` | The block that changed, when one did |

### `design:saved`
The design was saved. Lettrove saves as your user works, so this comes shortly after edits.

| Field | |
|---|---|
| `designId` | Keep this with your own record |
| `revision` | Goes up by one with each save |

### `selection:changed`
The selected block changed.

| Field | |
|---|---|
| `blockId` | The block, or `null` when nothing is selected |
| `type` | `heading`, `image`, `button`… or `null` |

### `image:uploaded`
Your user uploaded an image and it is ready to use.

| Field | |
|---|---|
| `url` | Where it is served from |
| `width`, `height` | Its size in pixels, when known |
| `id` | The stored image's id, when the store gave one |

### `theme:changed`
Your user switched light or dark from the editor's own switch.

| Field | |
|---|---|
| `theme` | What they picked: `light`, `dark` or `auto` |
| `applied` | What the editor shows now: `light` or `dark` |

### `config:adjusted`
An option you passed was dropped or changed: an invalid option with a live key, or something the
project's plan does not include. See [Options only narrow](/docs/editor/options#options-only-narrow).

| Field | |
|---|---|
| `option` | The option's path, e.g. `tools.disabled` |
| `reason` | Why, in words |

### `error`
Something went wrong that you may want to show or log.

| Field | |
|---|---|
| `code` | A stable code from the [error codes](/docs/api/errors) |
| `message` | What happened, in words. Messages may be reworded; codes never change meaning. |
| `recoverable` | `true` when the editor carries on by itself |