---
title: "Events"
description: "The shipped events delivery mechanism — on / off / once over a typed event map, returning a Disposable. Per-event emission readiness is labeled individually."
canonical: https://amnesia-docs.pages.dev/api/reference/events/
source: "src/content/docs/api/reference/events.md"
---

# Events

:::tip[Shipped — public-stable (mechanism only)]
The `.events` **delivery mechanism** (`on` / `off` / `once`) is part of the first-release shipped
surface. **Individual event readiness is labeled per event** — see the
[per-event readiness table](#per-event-readiness). Subscribing to an event that does not fire is safe,
but your handler simply never runs.
:::

The events facade is a typed, notify-only subscription mechanism over a fixed event map. Subscribing
returns a `Disposable` you can use to unsubscribe.

```js
const api = window.Amnesia; // or this.app.plugins.plugins['amnesia']?.api

const sub = api.events.on('note-created', (payload) => {
  // react to the new note
});

// later — clean up:
sub.dispose();
```

## Methods

| Method | Purpose | Returns |
| --- | --- | --- |
| `on(eventName, handler)` | Subscribe to an event for every emission. | `Disposable` |
| `once(eventName, handler)` | Subscribe for a single emission, then auto-unsubscribe. | `Disposable` |
| `off(eventName, handler)` | Unsubscribe a previously registered handler. | `void` |

Event names are typed against the reader event map; `on`/`once` return a `Disposable`.

## Clean up with Disposable

Every subscription returns a `Disposable` with a `dispose()` method. Always dispose your subscriptions
on unload to avoid leaked listeners — the most common cause of plugin instability:

```js
// In a plugin, tie the subscription to the plugin lifecycle:
const sub = api.events.on('link-created', onLink);
this.register(() => sub.dispose());
```

## Per-event readiness

The mechanism is shipped, but **whether a given event fires depends on the facade that emits it**, and
those facades are at different readiness tiers. Each event class is labeled individually:

| Event class | Members | Readiness | Notes |
| --- | --- | --- | --- |
| Notes / links | `note-*`, `link-*` | **Shipped** | Fire today; emitted by the shipped notes/links facades. |
| Highlights | `highlight-created`, `highlight-updated`, `highlight-deleted` | **Experimental** | Emit at runtime, but the emitting facade is [experimental](/api/reference/experimental-surfaces/) and unproven. Do not treat as shipped. |
| Reader / content / navigation | `relocated`, `page-turn`, `rendered`, `text-selected`, … | **Not available** | Do **not** fire today — they depend on the scaffolded reader bridge. |
| Collection | `collection-*` | **Not available** | Emitted only by an unwired bridge; untyped (not in the reader event map). |

Subscribing to a not-available event is harmless but useless until the underlying surface is wired.

## Related

- Guide: [Subscribe to events](/api/guides/subscribe-to-events/)
- [`commands.notes`](/api/reference/commands-notes/) and [`commands.links`](/api/reference/commands-links/) (emit the shipped events)
- [Experimental surfaces](/api/reference/experimental-surfaces/) (the `highlights` facade that emits the experimental highlight events)

<sub>Reference verified as of 2026-06-28.</sub>