Subscribe to events

This guide covers the shipped events delivery mechanism: how to subscribe, how to clean up, and which events actually fire today.

1. Subscribe

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:

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:

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.

Next steps

• Add notes and links (the facades that emit the shipped events)
• Events reference

_{Reference verified as of 2026-06-28.}