# Events

> Every document engine event with its payload: save:status, history:change, load, recovery, export and version events, and how to unsubscribe.

Source: https://fabricjs-document-engine.jscrate.dev/docs/api/events
Last updated: 2026-09-28

The engine reports what it does through document engine events. Subscribe with `engine.on(name, handler)`. It returns a function that unsubscribes. Payloads are fully typed through `DocumentEngineEvents`.

```ts
const unsubscribe = engine.on("save:status", ({ status }) => {
  statusLabel.textContent = status;
});

unsubscribe();
```

In React, `useDocumentEvent(engine, name, handler)` subscribes with the latest handler.

## All document engine events

| Event                 | Payload                                      | When                                     |
| --------------------- | -------------------------------------------- | ---------------------------------------- |
| `load:start`          | `{ documentId }`                             | A load begins                            |
| `document:change`     | `{ documentId }`                             | Another document is now open             |
| `load:success`        | `{ document, warnings, migratedFrom }`       | A load finished                          |
| `load:error`          | `{ error }`                                  | A load failed. The canvas is unchanged   |
| `assets:warning`      | `{ warnings }`                               | Images or fonts need attention           |
| `save:start`          | `{ document }`                               | A save begins                            |
| `save:success`        | `{ document }`                               | A save finished                          |
| `save:error`          | `{ error }`                                  | A save failed after all retries          |
| `save:retry`          | `{ attempt, delay, error }`                  | A failed save will be retried            |
| `save:status`         | `SaveState`                                  | The save status changed                  |
| `history:change`      | `{ canUndo, canRedo, undoLabel, redoLabel }` | Undo or redo became available or changed |
| `history:error`       | `{ error }`                                  | Undo or redo could not rebuild an object |
| `recovery:checkpoint` | `{ documentId, savedAt }`                    | A recovery copy was written              |
| `recovery:restored`   | `{ document }`                               | A recovery copy was restored             |
| `recovery:error`      | `{ error }`                                  | A recovery copy could not be written     |
| `export:success`      | `{ format, width, height, warnings }`        | An export finished                       |
| `export:error`        | `{ error }`                                  | An export failed                         |
| `version:created`     | `VersionSummary`                             | A version was kept                       |
| `version:restored`    | `{ version, document }`                      | A version was restored                   |
| `version:error`       | `{ error }`                                  | An automatic version failed              |

Every `error` is a `DocumentEngineError` with a stable `code`. See [error codes](https://fabricjs-document-engine.jscrate.dev/docs/api/error-codes).

## The ones most apps need

- `save:status` drives the save indicator.
- `history:change` drives the undo and redo buttons.
- `load:error` and `save:error` drive error messages.

If you want every value at once, `createDocumentStateStore` combines these document engine events into one snapshot. See [plain JavaScript](https://fabricjs-document-engine.jscrate.dev/docs/frameworks/vanilla-js).