connect.notifications

Show OS-level toast notifications. Per instance, up to 10 live at a time; reusing an id replaces the existing toast.

• Capability: notifications
• Namespace: connect.notifications

📷

Screenshot

caption: A system notification raised by an extension. Capture an OS toast created via notifications.create.

drop the image at public/docs-img/extensions/notification.png

Walkthrough

Notify on completion, and react to a click.

1. Declare notifications:

   { "capabilities": ["notifications"] }

2. Show a toast and keep its id:

   const { id } = await connect.notifications.create({ title: 'Done', message: 'Export ready.' });

3. Handle a click with onClicked.
4. Update progress by reusing the same id (replaces the toast).

Methods

notifications.create(options)

Show a toast.

How to use it

1. Pass at least a title; add message / iconUrl as needed.
2. Reuse an id to replace a live toast (e.g. progress); read { id, shown }.

Signature — connect.notifications.create({ id?, title, message?, iconUrl?, buttons? })

Parameters

Returns — Promise<{ id, shown }> — shown: false on a headless host.

const { id } = await connect.notifications.create({
  title: 'Done', message: 'Your export is ready.',
});

notifications.clear(id)

Close a toast.

How to use it

1. Pass the id returned by create to dismiss it.

Signature — connect.notifications.clear(id) · Returns Promise<void>.

Events

notifications.onClicked(cb)

Fires when the user clicks one of your toasts. Wakes a suspended background.

How to use it

1. Subscribe once.
2. Match the { id } back to what the toast was about, and act.

Payload — { id }.

connect.notifications.onClicked(({ id }) => focusRelated(id));

notifications.onButtonClicked(cb)

Fires when the user clicks one of your toast's buttons. Wakes a suspended background.

How to use it

1. Create the toast with buttons: [{ title: 'Open' }, { title: 'Dismiss' }].
2. Subscribe once; branch on buttonIndex (0-based, matching your buttons array).

Payload — { id, buttonIndex }.

const { id } = await connect.notifications.create({
  title: 'Export ready', buttons: [{ title: 'Open' }, { title: 'Dismiss' }],
});
connect.notifications.onButtonClicked(({ id, buttonIndex }) => {
  if (buttonIndex === 0) openExport(id);
});

Edge cases

• Buttons render where the OS notifier supports actions (macOS today); on other platforms the toast shows without them and onButtonClicked simply never fires — keep onClicked as the universal path.

Notes

• Keep to 10 live toasts; beyond that, older ones are dropped. Replace-by-id is the way to update a running notification (e.g. progress).