---
title: "Subscribe to events"
description: "Subscribe to typed Amnesia events with on and once, clean up with Disposable, and know which events fire today."
canonical: https://amnesia-docs.pages.dev/api/guides/subscribe-to-events/
source: "src/content/docs/api/guides/subscribe-to-events.md"
---

# Subscribe to events

This guide covers the shipped [events](/api/reference/events/) delivery mechanism: how to subscribe,
how to clean up, and which events actually fire today.

## 1. Subscribe

```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
});
```

Use `once` for a single emission:

```js
api.events.once('link-created', (payload) => {
  // runs once, then auto-unsubscribes
});
```

## 2. Always clean up with Disposable

Every `on`/`once` call returns a `Disposable`. Leaked listeners are the most common cause of plugin
instability — tie each subscription to your unload:

```js
const sub = api.events.on('note-updated', onUpdate);

// In a plugin:
this.register(() => sub.dispose());

// Or unsubscribe explicitly:
// sub.dispose();
// api.events.off('note-updated', onUpdate);
```

## 3. Know which events fire

The delivery mechanism is shipped, but individual events are at different readiness tiers. Subscribe with
this in mind:

| Event class | Examples | Fires today? |
| --- | --- | --- |
| Notes / links | `note-created`, `link-created` | **Yes — shipped** |
| Highlights | `highlight-created` | Yes, but **experimental** — may change without notice |
| Reader / content / navigation | `relocated`, `page-turn`, `text-selected` | **No** — not wired yet |
| Collection | `collection-*` | **No** — not wired/typed |

Subscribing to an event that does not fire is harmless: your handler simply never runs. See the full
[per-event readiness table](/api/reference/events/#per-event-readiness).

## Next steps

- [Add notes and links](/api/guides/add-notes-and-links/) (the facades that emit the shipped events)
- [Events reference](/api/reference/events/)

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