Skip to main content
The Events class provides a simple event emitter implementation for listening to and triggering custom events throughout your plugin.

​
Overview

The Events class allows you to implement the observer pattern, where different parts of your plugin can communicate through events without tight coupling. This is the base class for many Obsidian API classes that need to emit events.

​
Constructor

const events = new Events();

​
Methods

​
on

Register an event handler callback. 
on(name: string, callback: (...data: unknown[]) => unknown, ctx?: any): EventRef
​
name
string
required
The name of the event to listen for
​
callback
function
required
The callback function to execute when the event is triggered. Receives any data passed during trigger()
​
ctx
any
Optional context (this binding) for the callback function
​
return
EventRef
A reference to the event registration that can be used with offref() or Component.registerEvent()

​
Example

class MyPlugin extends Plugin {
  onload() {
    // Listen to a custom event
    this.registerEvent(
      this.app.workspace.on('custom-event', (data) => {
        console.log('Custom event fired:', data);
      })
    );
  }
}

​
off

Unregister an event handler by name and callback. 
off(name: string, callback: (...data: unknown[]) => unknown): void
​
name
string
required
The name of the event to stop listening for
​
callback
function
required
The exact callback function that was registered

​
Example

const handler = (data: any) => {
  console.log(data);
};

events.on('my-event', handler);
// Later...
events.off('my-event', handler);

​
offref

Unregister an event handler using an EventRef. 
offref(ref: EventRef): void
​
ref
EventRef
required
The EventRef returned by on() when the event was registered

​
Example

const ref = events.on('my-event', (data) => {
  console.log(data);
});

// Later...
events.offref(ref);

​
trigger

Trigger an event and call all registered handlers. 
trigger(name: string, ...data: unknown[]): void
​
name
string
required
The name of the event to trigger
​
data
unknown[]
Any number of arguments to pass to the event handlers

​
Example

class MyComponent extends Events {
  doSomething() {
    // Do work...
    
    // Notify listeners
    this.trigger('work-completed', { result: 'success' });
  }
}

​
tryTrigger

Attempt to trigger a specific event reference. 
tryTrigger(evt: EventRef, args: unknown[]): void
​
evt
EventRef
required
The event reference to trigger
​
args
unknown[]
required
Array of arguments to pass to the event handler

​
Best Practices

​
Use Component.registerEvent()

When working within a Component or Plugin, always use registerEvent() to automatically clean up event listeners when the component unloads: 
class MyPlugin extends Plugin {
  onload() {
    // This will be automatically cleaned up on plugin unload
    this.registerEvent(
      this.app.workspace.on('active-leaf-change', () => {
        console.log('Active leaf changed');
      })
    );
  }
}

​
Custom Event Classes

Extend the Events class to create custom event emitters: 
class DataStore extends Events {
  private data: Map<string, any> = new Map();

  set(key: string, value: any) {
    this.data.set(key, value);
    this.trigger('change', key, value);
  }

  get(key: string) {
    return this.data.get(key);
  }
}

const store = new DataStore();
store.on('change', (key, value) => {
  console.log(`Data changed: ${key} = ${value}`);
});

store.set('username', 'Alice'); // Logs: Data changed: username = Alice

​
See Also

Build docs developers (and LLMs) love

Get started for freeTalk to us