dash.on and dash.emit

Send an event from one pane and receive it in the other panes on the same canvas. Use it to link panes, for example a list where picking a city updates a weather pane.

dash.on(event: string, cb: (payload: unknown) => void): () => void
dash.emit(event: string, payload?: unknown): void

Example

In the pane with the list, send the city that was picked:

for (const button of document.querySelectorAll('button[data-city]')) {
  button.addEventListener('click', () => {
    dash.emit('city-selected', { city: button.dataset.city });
  });
}

In the weather pane, listen for it. Any pane on the canvas can send this event, so check the payload before you use it:

dash.on('city-selected', (payload) => {
  const city = typeof payload?.city === 'string' ? payload.city : '';
  document.querySelector('#city').textContent = city;
});

Who receives an event

• Only the other panes on the same canvas. Events never reach a pane on another canvas.
• The pane that sends an event does not receive it, even if it listens to that name. Another copy of the same pane on the canvas does.
• Only panes listening at that moment. Events are not stored or replayed, so a pane that starts later does not see earlier ones.
• Panes that are scrolled out of view still receive events, as long as they have loaded.
• In the editor’s preview there are no other panes, so emit reaches nobody.

Behaviour

• The payload is copied as JSON, so listeners get what JSON.parse(JSON.stringify(payload)) gives. Without a payload, listeners get undefined.
• emit returns nothing and does not wait for delivery. A failure after it has returned, such as going over the rate limit, is written as a warning to the browser console of the pane’s frame and is not thrown.
• You can add several listeners for one name. Each call to on returns a function that removes that listener.

Errors

Neither call returns a promise. Both throw a DashError straight away when their arguments are wrong:

Code	Why
VALIDATION_FAILED	The event name is not a string of 1 to 64 characters, the payload has no JSON form or is larger than 16 KB as JSON, or cb is not a function.

A pane can listen to up to 100 different event names. Past that, on still returns, but no events arrive for the new name, and a LIMIT_REACHED warning goes to the frame’s browser console. An error thrown inside cb is reported like any uncaught error in the pane.

Limits

• An event name can be 1 to 64 characters.
• A payload can be up to 16 KB, measured as JSON.
• A pane can listen to up to 100 different event names.
• A pane can send up to 200 messages a second to the app. Every emit, on, fetch, storage and log call counts.