Customize toasts

covers rendering them. Toasts are a web component, so theming and custom rendering are web-only.

Theme

Theme toasts with lightTheme / darkTheme (a CourierToastTheme). Set mode to "light", "dark", or "system". The default is "system", which follows the user’s OS setting.

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

const lightTheme = { /* CourierToastTheme */ };
const darkTheme = { /* CourierToastTheme */ };

<CourierToast lightTheme={lightTheme} darkTheme={darkTheme} mode="system" />;

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

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

  const toast = document.getElementById("toast");
  toast.setLightTheme({ /* CourierToastTheme */ });
  toast.setDarkTheme({ /* CourierToastTheme */ });
</script>

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

const lightTheme = { /* CourierToastTheme */ };
const darkTheme = { /* CourierToastTheme */ };
</script>

<template>
  <CourierToast :lightTheme="lightTheme" :darkTheme="darkTheme" mode="system" />
</template>

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

@Component({
  selector: "app-toast",
  standalone: true,
  imports: [CourierToastComponent],
  template: `<courier-toast [lightTheme]="lightTheme" [darkTheme]="darkTheme" mode="system"></courier-toast>`,
})
export class ToastComponent {
  lightTheme: CourierToastTheme = { /* ... */ };
  darkTheme: CourierToastTheme = { /* ... */ };
}

The object is the same on React, Vue, Angular, and the Web Components, so it is documented once below.

A toast item has a default border: 1px solid #E5E5E5 in light mode, 1px solid #3A3A3A in dark. Override it with item.border.

CourierToastTheme reference

Every property is optional, and it is a shallower object than the inbox theme: one item key, not a tree of popup and inbox.

type CourierToastTheme = {
  item?: {
    backgroundColor?: string;
    hoverBackgroundColor?: string;
    activeBackgroundColor?: string;
    autoDismissBarColor?: string;      // the countdown bar
    title?: FontTheme;
    body?: FontTheme;
    icon?: IconTheme & { visible?: boolean };
    dismissIcon?: IconTheme & { visible?: boolean };
    shadow?: string;
    border?: string;
    borderRadius?: string;
    actions?: ActionVariantTheme & {
      button?: ActionVariantTheme;     // style: 'button', the filled default
      secondary?: ActionVariantTheme;  // style: 'secondary', outlined
      tertiary?: ActionVariantTheme;   // style: 'tertiary', borderless
      link?: ActionVariantTheme;       // style: 'link', inline text
    };
  };
};

type FontTheme = { family?: string; weight?: string; size?: string; color?: string };
type IconTheme = { color?: string; svg?: string };

type ActionVariantTheme = {
  backgroundColor?: string;
  hoverBackgroundColor?: string;
  activeBackgroundColor?: string;
  border?: string;
  borderRadius?: string;
  shadow?: string;
  textDecoration?: string;
  padding?: string;
  font?: FontTheme;
};

actions carries a default at its top level and one override per style. Fields set directly on actions apply to every action button. The button, secondary, tertiary, and link keys layer over that, each for actions asking for that look. So set shared padding once on actions, and only the colours per variant. Setting icon.visible to false drops the icon and the space it reserved, for toasts that read better as text alone.

The built-in toast is web-only, so there is no native toast theme. On iOS, Android, Flutter, and React Native, listen for new messages and style your own UI. See .

Custom UI

On the web SDKs, toasts support the same custom rendering as the inbox.

Replace the toast item

Swap the toast item for your own element while the SDK keeps managing the feed:

<CourierToast renderToastItem={(props) => <MyToast message={props?.message} />} />

const toast = document.querySelector("courier-toast");
toast.setToastItem((props) => renderToast(props));

<CourierToast :renderToastItem="(props) => renderToast(props)" />

<courier-toast>
  <ng-template #toastItem let-props>
    <!-- your custom toast; props.message is available -->
  </ng-template>
</courier-toast>

Skip the component: subscribe to the datastore and react to new messages with onMessageAdd. The datastore comes from @trycourier/courier-ui-inbox on every framework. Only the lifecycle wiring differs.

import { useEffect } from "react";
import { CourierInboxDatastore, CourierInboxDataStoreListener } from "@trycourier/courier-ui-inbox";

useEffect(() => {
  const listener = new CourierInboxDataStoreListener({
    onMessageAdd: (message, index, datasetId) => showMyPopup(message),
  });
  CourierInboxDatastore.shared.addDataStoreListener(listener);

  return () => CourierInboxDatastore.shared.removeDataStoreListener(listener);
}, []);

import { CourierInboxDatastore, CourierInboxDataStoreListener } from "@trycourier/courier-ui-inbox";

const listener = new CourierInboxDataStoreListener({
  onMessageAdd: (message, index, datasetId) => showMyPopup(message),
});
CourierInboxDatastore.shared.addDataStoreListener(listener);

<script setup lang="ts">
import { onMounted, onUnmounted } from "vue";
import { CourierInboxDatastore, CourierInboxDataStoreListener } from "@trycourier/courier-ui-inbox";

const listener = new CourierInboxDataStoreListener({
  onMessageAdd: (message, index, datasetId) => showMyPopup(message),
});

onMounted(() => CourierInboxDatastore.shared.addDataStoreListener(listener));
onUnmounted(() => CourierInboxDatastore.shared.removeDataStoreListener(listener));
</script>

import { Component, OnDestroy, OnInit } from "@angular/core";
import { CourierInboxDatastore, CourierInboxDataStoreListener } from "@trycourier/courier-ui-inbox";

@Component({ /* ... */ })
export class ToastPopupComponent implements OnInit, OnDestroy {
  private listener = new CourierInboxDataStoreListener({
    onMessageAdd: (message, index, datasetId) => this.showMyPopup(message),
  });

  ngOnInit() {
    CourierInboxDatastore.shared.addDataStoreListener(this.listener);
  }

  ngOnDestroy() {
    CourierInboxDatastore.shared.removeDataStoreListener(this.listener);
  }
}

See for the full inbox datastore surface.

Get started

Quickstarts

Inbox

Toasts

Preferences

Web Components

Customize toasts

Theme

CourierToastTheme reference

Custom UI

Replace the toast item

​Theme

​CourierToastTheme reference

​Custom UI

​Replace the toast item

​Show your own popup

Theme

CourierToastTheme reference

Custom UI

Replace the toast item

Show your own popup