Toast API / Guide

Valenced plugin guide

Toasts that feel at home in Discord.

Show a notification, keep its ID, and update it as work happens. The Toast API handles the shared UI, timing, stacking, and motion for you.

Shared renderer One dependency One renderer Per-toast control

Install the Toast API plugin first. Your plugin must declare it as a dependency so Valenced starts it before your plugin needs the API.

Get connected

1 Declare the dependency

Add the Toast API plugin ID to your manifest.

2 Choose how to access it

Use api.toasts or api.unscoped.toasts; both reach the same API.

3 Keep the returned ID

Use it to update or close the exact toast you created.

manifest.json 
{
  "dependencies": {
    "dev.kmmiio99o.toast.api": {
      "version": ">=1 <2"
    }
  }
}
Scoped access 
export default plugin({
  start(api) {
    api.toasts.show({
      content: 'Saved to your library',
      variant: 'success',
    })
  },
})
Unscoped access 
export default plugin({
  start(api) {
    api.unscoped.toasts.show('Saved to your library')
  },
})

The scoped API is attached to your plugin by the Toast API dependency. The unscoped form comes from the shared API registry; both references point to the same instance, toast stack, and settings. Pick whichever access path fits the surrounding code.

Try the update flow

This browser preview is illustrative. In your plugin, call show() once and update the returned ID.

✓ Ready when you are

Choose what to read next

Toast options covers message content, variants, icons, custom presses, and all fields accepted by ToastInput. Methods & lifecycle explains de-duplication, updates, timers, subscriptions, and dismissal callbacks.

Shared settings documents each setting and its default. These settings are shared by every plugin using this API, so prefer per-toast options when a choice only belongs to one message.

Next Explore toast options