Add toasts

Toasts share the inbox’s feed and . This page only covers rendering the toast component. Try it live:

Toast demo

See toasts pop up for new messages.

Toasts are transient popups that appear when a new message arrives. Render them on their own or alongside the inbox.

A Courier toast for a newly delivered message, with the message title, body, and Accept and Pass actions — A Courier toast appearing for a new message

The built-in toast is web-only. On iOS, Android, Flutter, and React Native, listen for new messages and show your own UI (mobile tabs below). Or use .

Set up

Install the SDK for your framework:

npm install @trycourier/courier-react
# On React 17? Use @trycourier/courier-react-17 instead (identical API):
# npm install @trycourier/courier-react-17

npm install @trycourier/courier-ui-toast

npm install @trycourier/courier-vue

npm install @trycourier/courier-angular

# Swift Package Manager: add https://github.com/trycourier/courier-ios
# or CocoaPods:
pod 'Courier_iOS'

# In settings.gradle add the JitPack repo, then the dependency in build.gradle:
# maven { url 'https://jitpack.io' }
# implementation 'com.github.trycourier:courier-android:<version>'

flutter pub add courier_flutter

npm install @trycourier/courier-react-native
# then, for iOS:
cd ios && pod install

On mobile, the SDK also needs native project setup before it renders: , , , and . Then with the same signIn as the inbox and render the component. The web SDKs use the built-in CourierToast. On mobile, listen for new messages and show your own UI:

import { CourierToast } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

export default function App() {
  // Renders toasts for new messages on the authenticated user's feed
  return <CourierToast />;
}

<courier-toast></courier-toast>

<script type="module">
  import { Courier } from "@trycourier/courier-ui-toast";

  Courier.shared.signIn({ userId, jwt });
</script>

<script setup lang="ts">
import { CourierToast } from "@trycourier/courier-vue";
</script>

<template>
  <CourierToast />
</template>

import { Component } from "@angular/core";
import { CourierToastComponent } from "@trycourier/courier-angular";

@Component({
  selector: "app-toast",
  standalone: true,
  imports: [CourierToastComponent],
  template: `<courier-toast></courier-toast>`,
})
export class ToastComponent {}

// No built-in toast on iOS: listen for new messages and show your own UI
let listener = await Courier.shared.addInboxListener(
  onMessageEvent: { message, index, feed, event in
    if event == .added {
      showMyToast(message) // your own toast UI
    }
  }
)

// No built-in toast on Android: listen and show your own UI
// addInboxListener is a suspend function; call it from a coroutine
lifecycleScope.launch {
  val listener = Courier.shared.addInboxListener(
    onMessageEvent = { message, index, feed, event ->
      if (event == InboxMessageEvent.ADDED) {
        showMyToast(message) // your own toast UI
      }
    }
  )
}

// No built-in toast on Flutter: listen and show your own UI
final listener = await Courier.shared.addInboxListener(
  onMessageEvent: (message, index, feed, event) {
    if (event == InboxMessageEvent.added) {
      showMyToast(message); // your own toast UI
    }
  },
);

// No built-in toast on React Native: listen and show your own UI
const listener = await Courier.shared.addInboxListener({
  onMessageEvent: (message, index, feed, event) => {
    if (event === "added") {
      showMyToast(message); // your own toast UI
    }
  },
});

Full SDK references: , , , , , , , .

Handle clicks

A toast fires two events: one when the body is clicked, and one for each the message carries. Action buttons do nothing by default. You decide where they go.

A Courier toast notification with two action buttons below the message body — A toast with action buttons. Each button raises its own click event.

<CourierToast
  onToastItemClick={({ message }) => {
    console.log("Toast clicked:", message);
  }}
  onToastItemActionClick={({ message, action }) => {
    window.open(action.href);
  }}
/>

<courier-toast id="my-toast"></courier-toast>

<script type="module">
  import { Courier, CourierToastDatastore } from "@trycourier/courier-ui-toast";

  const toast = document.getElementById("my-toast");

  toast.onToastItemClick(({ message }) => {
    window.open(message.actions[0].href);
  });

  toast.onToastItemActionClick(({ message, action }) => {
    window.open(action.href);
    CourierToastDatastore.shared.removeMessage(message);
  });
</script>

<CourierToast
  :on-toast-item-click="({ message }) => console.log('Toast clicked:', message)"
  :on-toast-item-action-click="({ action }) => window.open(action.href)"
/>

// <courier-toast (toastItemClick)="onClick($event)"
//                (toastItemActionClick)="onActionClick($event)"></courier-toast>

onClick({ message }: CourierToastItemClickEvent) { /* ... */ }
onActionClick({ action }: CourierToastItemActionClickEvent) { window.open(action.href); }

Both events carry the InboxMessage. The action event also carries the clicked InboxAction. Every callback the component accepts is in below.

Mobile has no built-in toast. Handle clicks in the UI you render from the inbox listener above.

Props

<CourierToast /> in React, Vue, and Angular. The web component takes the same values as kebab-case attributes, and courier-toast is the element name.

Prop	Type	Default	Description
`lightTheme`	`CourierToastTheme`		Theme applied in light mode.
`darkTheme`	`CourierToastTheme`		Theme applied in dark mode.
`mode`	`CourierComponentThemeMode`	`"system"`	Force light or dark instead of following the system.
`autoDismiss`	boolean	`false`	Dismiss each toast on a timer, with a countdown bar across the top.
`autoDismissTimeoutMs`	number	`5000`	How long a toast stays up when `autoDismiss` is on.
`dismissButton`	`"visible"`, `"hidden"`, `"hover"`, `"auto"`	`"auto"`	When the close button shows.
`onToastItemClick`	`(props) => void`		Called when a toast is clicked.
`onToastItemActionClick`	`(props) => void`		Called when a toast’s action button is clicked.
`renderToastItem`	`(props) => Element`		Replace the whole toast. See .
`renderToastItemContent`	`(props) => Element`		Replace the toast’s content, keeping its frame.
`onReady`	`(ready: boolean) => void`		Called once the component can accept messages.
`style`	`CSSProperties`	`position: fixed`, `width: 380px`, `top: 30px`, `right: 30px`, `z-index: 999`	Inline styles on the stack. Overriding one key keeps the rest.

dismissButton defaults to "auto", which means the button is always visible while autoDismiss is off and appears on hover once it is on. "hidden" removes it, which leaves a toast with no manual way out, so pair it with autoDismiss.

What auto-dismiss actually does

Only the top toast counts down. The rest of the stack is held paused until it becomes the top one, so three toasts at a 5 second timeout clear over 15 seconds rather than together. Hovering anywhere on the stack pauses every countdown, and leaving it resumes them, so a toast a reader is part-way through does not vanish under the cursor. The countdown bar pauses with it.

Waiting for the component with onReady

A toast can arrive before the component has mounted, and a custom render function registered too early is dropped. Both show up as toasts that never appear, or that appear unstyled. Sign in from onReady when either applies.

const [toastReady, setToastReady] = useState(false);

useEffect(() => {
  if (toastReady) {
    courier.shared.signIn({ userId: "user_123", jwt });
  }
}, [toastReady]);

return <CourierToast onReady={setToastReady} renderToastItem={(props) => <CustomToast {...props} />} />;

Verify

Open a screen with the toast component

Send a test message

to that user on the inbox channel.

Confirm the toast

A toast pops up for the new message.

Get started

Quickstarts

Inbox

Toasts

Preferences

Web Components

Toast demo

Set up

Handle clicks

Props

What auto-dismiss actually does

Waiting for the component with onReady

Verify

Toast demo

​Set up

​Handle clicks

​Props

​What auto-dismiss actually does

​Waiting for the component with onReady

​Verify

Set up

Handle clicks

Props

What auto-dismiss actually does

Waiting for the component with onReady

Verify