Courier Web Components SDK

The Courier Web Components SDK provides drop-in components for building notification experiences in any JavaScript project:

<courier-inbox> — full-featured inbox for displaying and managing messages
<courier-inbox-popup-menu> — popup menu version of the inbox
<courier-toast> — toast notifications for time-sensitive alerts
<courier-preferences> — notification preferences center for managing topic subscriptions and delivery

This is the latest version of the Courier Web Components SDK, recommended for new and existing apps.Coming from an earlier version? We recommend upgrading — check out the migration guide for the React SDK, which is a thin wrapper around these Web Components and exposes a similar API.

Installation

Inbox, Toast, and Preferences are published as separate packages. Install only the ones you need.

npm install @trycourier/courier-ui-inbox

npm install @trycourier/courier-ui-toast

npm install @trycourier/courier-ui-preferences

Available on GitHub and npm: Inbox · Inbox · Toast · Toast · Preferences · Preferences The Courier SDKs work with any JavaScript build system and do not require any additional build configuration.

Using React? Check out the Courier React SDK, which provides React components and hooks built on top of these Web Components.

Authentication

To use the SDK, you need to generate a JWT (JSON Web Token) for your user. This JWT should always be generated by your backend server, never in client-side code.

Inbox and Toast share the same Courier.shared authentication instance and connection to the Courier backend. Authenticate once and both components work.

JWT Authentication Flow

Your client calls your backend

When your app needs to authenticate a user, your client should make a request to your own backend (ex. GET https://your-awesome-app.com/api/generate-courier-jwt).

Your backend calls Courier

In your backend endpoint, use your Courier API Key to call the Courier Issue Token Endpoint and generate a JWT for the user.

Your backend returns the JWT to your client

Having received the JWT from Courier, your backend should return it to your client and pass it to the Courier SDK.

See all available user scopes for the Courier APIs.

Development Authentication with cURL

To quickly test JWT generation for development only, you can use cURL to call the Courier Issue Token Endpoint directly.

Do not call the Issue Token API from client-side code. Always keep your Courier API keys secure.

curl --request POST \
     --url https://api.courier.com/auth/issue-token \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer $YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data \
 '{
    "scope": "user_id:$YOUR_USER_ID write:user-tokens inbox:read:messages inbox:write:events read:preferences write:preferences read:brands",
    "expires_in": "$YOUR_NUMBER days"
  }'

Inbox Web Components

`<courier-inbox>`

Importing the Courier SDK registers Courier’s Web Components (<courier-inbox>, <courier-inbox-popup-menu>).

<body>
  <courier-inbox id="inbox"></courier-inbox>

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

    // Generate a JWT for your user on your backend server
    const jwt = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

    // Authenticate the user with the inbox
    Courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: jwt
    });
  </script>
</body>

Sample App: See a complete working example in our Vanilla JS Inbox sample app.

If you’re using tenants, you can scope requests to a particular tenant by passing its ID to the signIn request.

Courier.shared.signIn({
  userId: "my-user-id",
  jwt: jwt,
  tenantId: "my-tenant-id"
});

For the full reference of sign in parameters, see the Courier JS docs.

<body>
  <div style="padding: 24px;">
    <courier-inbox-popup-menu id="inbox"></courier-inbox-popup-menu>
  </div>

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

    // Generate a JWT for your user on your backend server
    const jwt = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

    // Authenticate the user with the inbox
    Courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: jwt
    });
  </script>
</body>

Sample App: See a complete working example in our Vanilla JS Popup Menu sample app.

Tabs and Feeds

Tabs and feeds allow you to organize and filter messages in your inbox. A feed is a container that groups related tabs together. Each tab represents a filtered view of messages.

If there is only one feed, the feed selection dropdown is hidden. If a feed has only one tab, the tab bar is hidden and the unread count appears next to the feed.

Filter Property	Type	Description
`tags`	`string[]`	Messages that have any of the specified tags
`archived`	`boolean`	Whether to include archived messages (defaults to `false` if unset)
`status`	`'read' \| 'unread'`	Filter by read/unread status

Preview of CourierInbox with tabs — CourierInbox with many tabs

<body>
  <courier-inbox id="inbox"></courier-inbox>

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

    const inbox = document.getElementById('inbox');

    // Set feeds with multiple tabs
    inbox.setFeeds([
      {
        feedId: 'notifications',
        title: 'Notifications',
        tabs: [
          {
            datasetId: 'all-notifications',
            title: 'All',
            filter: {}
          },
          {
            datasetId: 'unread-notifications',
            title: 'Unread',
            filter: { status: 'unread' }
          },
          {
            datasetId: 'important',
            title: 'Important',
            filter: { tags: ['important'] }
          },
          {
            datasetId: 'archived',
            title: 'Archived',
            filter: { archived: true }
          }
        ]
      }
    ]);

    // Authenticate the user
    Courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    });
  </script>
</body>

Show Multiple feeds example

You can define multiple feeds to organize messages into different categories. Each feed appears as a selectable option in the inbox header.

Preview of CourierInbox with feeds — CourierInbox with many feeds

<body>
  <courier-inbox id="inbox"></courier-inbox>

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

    const inbox = document.getElementById('inbox');

    inbox.setFeeds([
      {
        feedId: 'all',
        title: 'All',
        iconSVG: '...',
        tabs: [
          { datasetId: 'all', title: 'All', filter: {} }
        ]
      },
      {
        feedId: 'jobs',
        title: 'Jobs',
        tabs: [
          { datasetId: 'jobs', title: 'Jobs', filter: { tags: ['job'] } }
        ]
      },
      {
        feedId: 'my-posts',
        title: 'My Posts',
        tabs: [
          { datasetId: 'all-my-posts', title: 'All', filter: {} },
          { datasetId: 'comments', title: 'Comments', filter: { tags: ['comment'] } },
          { datasetId: 'reactions', title: 'Reactions', filter: { tags: ['reaction'] } },
          { datasetId: 'reposts', title: 'Reposts', filter: { tags: ['repost'] } }
        ]
      },
      {
        feedId: 'mentions',
        title: 'Mentions',
        tabs: [
          { datasetId: 'mentions', title: 'Mentions', filter: { tags: ['mention'] } }
        ]
      }
    ]);

    Courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'
    });
  </script>
</body>

Handle Clicks and Presses

Use the onMessageClick(), onMessageActionClick(), and onMessageLongPress() methods to handle clicks and presses in the inbox.

onMessageLongPress() is only applicable on devices that support touch events.

<body>
  <courier-inbox id="inbox"></courier-inbox>

  <!-- Uncomment the line below to use the popup menu instead -->
  <!-- <courier-inbox-popup-menu id="inbox"></courier-inbox-popup-menu> -->

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

    // Generate a JWT for your user on your backend server
    const jwt = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...';

    // Authenticate the user with the inbox
    Courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: jwt
    });

    const inbox = document.getElementById('inbox');

    // Handle message clicks
    inbox.onMessageClick(({ message, index }) => {
      alert("Message clicked at index " + index +
            ":\n" + JSON.stringify(message, null, 2));
    });

    // Handle message action clicks (these are buttons on individual messages)
    inbox.onMessageActionClick(({ message, action, index }) => {
      alert(
        "Message action clicked at index " + index + ":\n" +
        "Action: " + JSON.stringify(action, null, 2) + "\n" +
        "Message: " + JSON.stringify(message, null, 2)
      );
    });

    // Handle message long presses (useful for mobile web)
    inbox.onMessageLongPress(({ message, index }) => {
      alert("Message long pressed at index " + index +
            ":\n" + JSON.stringify(message, null, 2));
    });
  </script>
</body>

Styles and Theming

The fastest way to style the Courier Inbox to match your app is with a custom theme.

You can customize fonts, icons, text, and more. Check out the CourierInboxTheme reference.

Courier Inbox with a custom unread indicator style

<body>
  <courier-inbox id="inbox"></courier-inbox>

  <!-- Uncomment the line below to use the popup menu instead -->
  <!-- <courier-inbox-popup-menu id="inbox"></courier-inbox-popup-menu> -->

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

    // Courier authentication...

    const inbox = document.getElementById('inbox');
    const theme = {
      inbox: {
        header: {
          filters: {
            unreadIndicator: {
              backgroundColor: "#8B5CF6"
            }
          }
        },
        list: {
          item: {
            unreadIndicatorColor: "#8B5CF6"
          }
        }
      }
    };

    // Apply the theme
    inbox.setLightTheme(theme);
    inbox.setDarkTheme(theme);

    // Set the mode ('light', 'dark', or 'system')
    inbox.setMode('light');
  </script>
</body>

Vertical Alignment	Options
Top	`"top-right"`, `"top-center"`, `"top-left"`
Center	`"center-right"`, `"center-center"`, `"center-left"`
Bottom	`"bottom-right"`, `"bottom-center"`, `"bottom-left"`

<body>
  <div style="display: flex; justify-content: center; align-items: center; padding: 100px;">

    <courier-inbox-popup-menu
      popup-alignment="top-right"
      top="44px"
      right="44px"
      popup-width="340px"
      popup-height="400px">
    </courier-inbox-popup-menu>
  </div>
</body>

Fixed height: <courier-inbox> has a default height of auto. Set a fixed height with the height attribute:

<body>
  <courier-inbox height="50vh"></courier-inbox>
</body>

Custom Elements

Customize individual parts of the inbox by passing factory functions that return HTML elements.

Show Custom list item

<body>
  <courier-inbox id="inbox"></courier-inbox>

  <script type="module">
    const inbox = document.getElementById('inbox');

    inbox.setListItem(({ message, index }) => {
      const pre = document.createElement('pre');
      pre.style.padding = '24px';
      pre.style.borderBottom = '1px solid #e0e0e0';
      pre.style.margin = '0';
      pre.textContent = JSON.stringify({ message, index }, null, 2);

      return pre;
    });
  </script>
</body>

Custom inbox message list item displaying the message object

Show Custom header

Call removeHeader() to remove the header entirely.The setHeader callback receives a props object with a feeds array. Each feed includes selection state, tabs with unread counts, and filter information.

<body>
  <courier-inbox id="inbox"></courier-inbox>

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

    const inbox = document.getElementById('inbox');

    inbox.setHeader((props) => {
      const headerDiv = document.createElement('div');
      headerDiv.style.background = 'red';
      headerDiv.style.fontSize = '20px';
      headerDiv.style.color = 'white';
      headerDiv.style.padding = '20px';
      headerDiv.style.width = '100%';
      headerDiv.style.fontFamily = 'monospace';

      const selectedFeed = props.feeds.find(feed => feed.isSelected);
      const selectedTab = selectedFeed?.tabs.find(tab => tab.isSelected);

      let feedPart = selectedFeed ? `${selectedFeed.title}` : 'No Feed Selected';
      let tabPart = selectedTab ? `${selectedTab.title}` : 'No Tab Selected';
      let unreadPart = typeof selectedTab?.unreadCount === 'number' ? `Unread: ${selectedTab.unreadCount}` : '';

      headerDiv.textContent = `${feedPart} / ${tabPart} ${unreadPart && '- ' + unreadPart}`;

      return headerDiv;
    });

    // Set up feeds and authenticate...
  </script>
</body>

Header Factory Props

{
  feeds: [
    {
      feedId: string;
      title: string;
      iconSVG?: string;
      tabs: [
        {
          datasetId: string;
          title: string;
          unreadCount: number;
          isSelected: boolean;
          filter: {
            tags?: string[];
            archived?: boolean;
            status?: 'read' | 'unread';
          };
        }
      ];
      isSelected: boolean;
    }
  ];
}

Show Custom popup menu button

<body>
  <div style="display: flex; justify-content: center; align-items: center; padding: 100px;">
    <courier-inbox-popup-menu id="inbox"></courier-inbox-popup-menu>
  </div>

  <script type="module">
    const inbox = document.getElementById('inbox');

    inbox.setMenuButton(({ unreadCount }) => {
      const button = document.createElement('button');
      button.textContent = `Open the Inbox Popup. Unread message count: ${unreadCount}`;
      return button;
    });
  </script>
</body>

Show Custom loading, empty, error, and pagination states

Subsequent pages of messages are loaded automatically when the user scrolls to the bottom of the inbox, so the pagination component may only be visible briefly.

<body>
  <courier-inbox id="inbox"></courier-inbox>

  <script type="module">
    const inbox = document.getElementById('inbox');

    inbox.setLoadingState(props => {
      const loading = document.createElement('div');
      loading.style.padding = '24px';
      loading.textContent = 'Custom Loading State';
      return loading;
    });

    inbox.setEmptyState(props => {
      const empty = document.createElement('div');
      empty.style.padding = '24px';
      empty.textContent = 'Custom Empty State';
      return empty;
    });

    inbox.setErrorState(props => {
      const error = document.createElement('div');
      error.style.padding = '24px';
      error.textContent = 'Custom Error State';
      return error;
    });

    inbox.setPaginationItem(props => {
      const pagination = document.createElement('div');
      pagination.style.padding = '24px';
      pagination.style.textAlign = 'center';
      pagination.textContent = 'Loading the next page of messages';
      return pagination;
    });
  </script>
</body>

Programmatic Control

The <courier-inbox> component exposes methods for programmatic control, allowing you to dynamically manage feeds, tabs, actions, and data refresh.

Feed and Tab Selection

Method	Description
`selectFeed(feedId)`	Switch to the specified feed and load its data.
`selectTab(tabId)`	Switch to the specified tab within the current feed.
`getFeeds()`	Returns the current array of configured feeds.
`currentFeedId` (getter)	Returns the ID of the currently selected feed.
`refresh()`	Forces a reload of inbox data, bypassing the cache. Returns `Promise<void>`.

Header Actions

Method	Description
`setActions(actions)`	Set header actions. Action IDs: `'readAll'`, `'archiveRead'`, `'archiveAll'`.
`setListItemActions(actions)`	Set list item actions. Action IDs: `'read_unread'`, `'archive_unarchive'`.

Method	Description
`showPopup()`	Open the popup programmatically with transition animation.
`closePopup()`	Close the popup programmatically with transition animation.

Static Helper Methods

Method	Description
`CourierInbox.defaultFeeds()`	Returns the default feeds (Inbox and Archive).
`CourierInbox.defaultActions()`	Returns the default header actions.
`CourierInbox.defaultListItemActions()`	Returns the default list item actions.

Show Programmatic feed/tab selection example

<body>
  <courier-inbox id="inbox"></courier-inbox>

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

    const inbox = document.getElementById('inbox');

    inbox.setFeeds([
      {
        feedId: 'notifications',
        title: 'Notifications',
        tabs: [
          { datasetId: 'all', title: 'All', filter: {} },
          { datasetId: 'unread', title: 'Unread', filter: { status: 'unread' } }
        ]
      },
      {
        feedId: 'archive',
        title: 'Archive',
        tabs: [
          { datasetId: 'archived', title: 'Archived', filter: { archived: true } }
        ]
      }
    ]);

    Courier.shared.signIn({ userId: $YOUR_USER_ID, jwt: '...' });

    // Programmatically select a feed and tab
    inbox.selectFeed('notifications');
    inbox.selectTab('unread');

    // Get current state
    console.log('Current feed:', inbox.currentFeedId);
    console.log('All feeds:', inbox.getFeeds());
  </script>
</body>

Show Actions configuration example

<body>
  <courier-inbox id="inbox"></courier-inbox>

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

    const inbox = document.getElementById('inbox');

    // Configure header actions
    inbox.setActions([
      { id: 'readAll', iconSVG: '...', text: 'Mark All Read' },
      { id: 'archiveRead', iconSVG: '...', text: 'Archive Read' }
    ]);

    // Configure list item actions
    inbox.setListItemActions([
      { 
        id: 'read_unread',
        readIconSVG: '...',
        unreadIconSVG: '...'
      },
      {
        id: 'archive_unarchive',
        archiveIconSVG: '...',
        unarchiveIconSVG: '...'
      }
    ]);
  </script>
</body>

Attribute vs Method Usage

Many configuration options can be set either via HTML attributes or programmatic methods:

HTML attributes: Best for initial, static configuration
Programmatic methods: Best for dynamic, runtime configuration

<!-- Using HTML attributes -->
<courier-inbox 
  mode="light"
  light-theme='{"inbox": {"backgroundColor": "#fff"}}'>
</courier-inbox>

<!-- Using programmatic methods -->
<courier-inbox id="inbox"></courier-inbox>
<script type="module">
  const inbox = document.getElementById('inbox');
  inbox.setMode('light');
  inbox.setLightTheme({
    inbox: { backgroundColor: '#fff' }
  });
</script>

Some features are only available via methods (e.g., selectFeed(), refresh(), getFeeds()) and cannot be set via attributes.

Toast Web Components

Toasts are short-lived notifications that notify users and prompt them to take action. The Toast component is connected to the feed of Courier Inbox messages.

Toasts are synced with the Inbox message feed. You can use both components together to provide persistent and temporary notifications.

`<courier-toast>`

Importing @trycourier/courier-ui-toast registers Courier’s Web Components (<courier-toast>).

<body>
  <courier-toast></courier-toast>

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

    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    Courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: jwt
    });
  </script>
</body>

Sample App: See a complete working example in our Vanilla JS Toast sample app.

HTML Attributes

A note on terminology: toast refers to the entire stack of toasts managed by <courier-toast>, while toast item refers to a single toast displayed for a message.

Attribute	Type	Default	Description
`auto-dismiss`	`boolean`	`false`	Whether toast items should auto-dismiss.
`auto-dismiss-timeout-ms`	`integer`	`5000`	If `auto-dismiss` is enabled, the timeout in milliseconds before dismissal.
`dismiss-button`	`"visible" \| "hidden" \| "hover" \| "auto"`	`"auto"`	Display option for the dismiss button. `"auto"` makes the button always visible if `auto-dismiss` is false, and visible on hover if `auto-dismiss` is true.
`light-theme`	`json`	`undefined`	JSON-stringified `CourierToastTheme` applied in light mode. Merged with defaults.
`dark-theme`	`json`	`undefined`	JSON-stringified `CourierToastTheme` applied in dark mode. Merged with defaults.
`mode`	`"light" \| "dark" \| "system"`	`"system"`	Theme mode for the toast component.

Toast component with auto-dismiss enabled.

If the auto-dismiss attribute is set, the dismiss button (x) will only be visible on hover and each toast item will automatically be dismissed. A countdown bar is shown to indicate the time remaining before the toast disappears.

Handle Clicks

API Method	Description
`onToastItemClick(handler)`	Called when a toast item is clicked.
`onToastItemActionClick(handler)`	Called when an action button on a toast item is clicked.

If a message contains actions, toast items will include a button for each. By default, these buttons do not implement any functionality.

index.html

<body>
  <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, toastItem }) => {
      window.open(message.actions[0].href);
    });

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

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

Show Click event types

type CourierToastItemClickEvent = {
  message: InboxMessage;
  toastItem: CourierToastItem | HTMLElement;
};

type CourierToastItemActionClickEvent = {
  message: InboxMessage;
  action: InboxAction;
};

Styles and Theming

Courier toasts with a custom light theme

index.html

<body>
  <courier-toast dismiss-button="hidden" id="my-toast"></courier-toast>

  <script type="module">
    import { Courier, CourierToastDatastore } from "@trycourier/courier-ui-toast";
    import ToastIcon from "./toast-icon.svg?raw";

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

    toast.setLightTheme({
      toast: {
        item: {
          title: {
            color: "#6366f1",
            weight: "bold",
          },
          backgroundColor: "#edeefc",
          border: "1px solid #cdd1ff",
          borderRadius: "15px",
          icon: {
            svg: ToastIcon
          }
        }
      }
    });

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

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

Toast items have a subtle default border: 1px solid #E5E5E5 in light mode and 1px solid #3A3A3A in dark mode. Override it with item.border.

Show type CourierToastTheme

export type CourierToastTheme = {
  item?: {
    backgroundColor?: string;
    hoverBackgroundColor?: string;
    autoDismissBarColor?: string;
    title?: {
      family?: string;
      weight?: string;
      size?: string;
      color?: string;
    };
    body?: {
      family?: string;
      weight?: string;
      size?: string;
      color?: string;
    };
    icon?: {
      color?: string;
      svg?: string;
    };
    dismissIcon?: {
      color?: string;
      svg?: string;
    };
    shadow?: string;
    border?: string;
    borderRadius?: string;
    actions?: {
      backgroundColor?: string;
      hoverBackgroundColor?: string;
      activeBackgroundColor?: string;
      border?: string;
      borderRadius?: string;
      shadow?: string;
      font?: {
        family?: string;
        weight?: string;
        size?: string;
        color?: string;
      };
    }
  }
}

Custom Elements

Method	Description
`setToastItemContent(factory)`	Customize the content area only, keeping default stack styling.
`setToastItem(factory)`	Fully replace each toast item for complete control.

Show Custom toast content example

index.html

<html>
<head>
  <link href="./styles.css" rel="stylesheet">
</head>
<body>
  <courier-toast id="my-toast" dismiss-button="hidden"></courier-toast>

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

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

    toast.setToastItemContent(({ message }) => {
      const content = document.createElement("div");
      content.className = "toast-content";

      const icon = document.createElement("img");
      icon.className = "toast-icon";
      icon.src = "./toast-icon.svg";
      icon.width = 24;
      icon.height = 24;

      const textContainer = document.createElement("div");
      textContainer.className = "toast-text";

      const title = document.createElement("strong");
      title.className = "toast-title";
      title.textContent = message.title;

      const body = document.createElement("p");
      body.className = "toast-body";
      body.textContent = message.body;

      textContainer.appendChild(title);
      textContainer.appendChild(body);

      const dismissButton = document.createElement("button");
      dismissButton.className = "toast-dismiss";
      dismissButton.textContent = "\u00d7";
      dismissButton.addEventListener("click", () => {
        CourierToastDatastore.shared.removeMessage(message);
      });

      content.appendChild(icon);
      content.appendChild(textContainer);
      content.appendChild(dismissButton);

      return content;
    });

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

Show Fully custom toast item example

auto-dismiss and auto-dismiss-timeout-ms remain valid when using custom items. If auto-dismiss is true, custom items are automatically removed after the timeout.

index.html

<html>
<head>
  <link href="./styles.css" rel="stylesheet">
</head>
<body>
  <courier-toast id="my-toast"></courier-toast>

  <script type="module">
    const toast = document.getElementById("my-toast");

    toast.setToastItem((props) => {
      const { message, dismiss } = props;

      const container = document.createElement("div");
      container.className = "toast-content";

      const messageDiv = document.createElement("div");
      messageDiv.className = "toast-message";

      const title = document.createElement("strong");
      title.className = "toast-title";
      title.textContent = message.title;

      const body = document.createElement("p");
      body.className = "toast-body";
      body.textContent = message.body;

      messageDiv.appendChild(title);
      messageDiv.appendChild(body);

      const actionsDiv = document.createElement("div");
      actionsDiv.className = "toast-actions";

      if (message.actions) {
        message.actions.forEach(action => {
          const button = document.createElement("button");
          button.className = "toast-action-button";
          button.textContent = action.content;
          button.onclick = () => {
            if (action.href) {
              window.open(action.href);
            }
          };
          actionsDiv.appendChild(button);
        });
      }

      container.appendChild(messageDiv);
      container.appendChild(actionsDiv);

      return container;
    });

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

Programmatic Control

Method	Description
`enableAutoDismiss()`	Enable auto-dismiss for toast items.
`disableAutoDismiss()`	Disable auto-dismiss. Items remain visible until manually dismissed.
`setAutoDismissTimeoutMs(ms)`	Set the auto-dismiss timeout in milliseconds.
`setDismissButton(option)`	Set dismiss button visibility: `'visible'`, `'hidden'`, `'hover'`, or `'auto'`.
`setMode(mode)`	Set theme mode: `'light'`, `'dark'`, or `'system'`.
`setLightTheme(theme)`	Set the light theme programmatically.
`setDarkTheme(theme)`	Set the dark theme programmatically.

Toast Datastore

CourierToastDatastore is the central repository of Inbox messages from which <courier-toast> listens for messages to display and dismiss. It is a singleton accessed through CourierToastDatastore.shared.

Method	Description
`addMessage(message)`	Add a message to display as a toast. Messages must include `messageId`.
`removeMessage(message)`	Remove a message, dismissing any displayed toast for it.

import { CourierToastDatastore } from "@trycourier/courier-ui-toast";

// Add a test message (useful for prototyping)
CourierToastDatastore.shared.addMessage({
  title: "Lorem ipsum dolor sit",
  body: "Lorem ipsum dolor sit amet",
  messageId: "abcd-1234-abcd-1234",
  actions: [{ "content": "Click me!" }]
});

// Remove a message (dismiss its toast)
CourierToastDatastore.shared.removeMessage(message);

Preferences Web Components

The Preferences component lets your users manage which topics they’re subscribed to and how each topic is delivered (per-channel routing and digest schedules), directly inside your app.

Preferences ship in their own package, @trycourier/courier-ui-preferences (see Installation) — it’s standalone and doesn’t require the inbox or toast packages.

npm install @trycourier/courier-ui-preferences

`<courier-preferences>`

Importing @trycourier/courier-ui-preferences registers the <courier-preferences> Web Component.

<body>
  <courier-preferences id="preferences"></courier-preferences>

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

    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    Courier.shared.signIn({
      userId: $YOUR_USER_ID,
      jwt: jwt
    });
  </script>
</body>

Preferences use the same authentication mechanism as the inbox, but the JWT must include the read:preferences and write:preferences scopes.

Preferences HTML Attributes

Attribute	Type	Default	Description
`light-theme`	`json`	`undefined`	JSON-stringified `CourierPreferencesTheme` applied in light mode. Merged with defaults.
`dark-theme`	`json`	`undefined`	JSON-stringified `CourierPreferencesTheme` applied in dark mode. Merged with defaults.
`mode`	`"light" \| "dark" \| "system"`	`"system"`	Theme mode for the component.
`tenant-id`	`string`	`undefined`	Scope preferences to a specific tenant (multi-tenant apps).
`brand-id`	`string`	`undefined`	Render preferences using a specific brand’s styling.

Preferences Styling and Theming

Set themes programmatically with setLightTheme(), setDarkTheme(), and setMode(). Themes are merged with the defaults, so you only need to specify what you want to override. The default accent color matches the Inbox component for a consistent look.

index.html

<body>
  <courier-preferences id="prefs"></courier-preferences>

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

    const prefs = document.getElementById("prefs");

    prefs.setLightTheme({
      primaryColor: "#8B5CF6",
      container: { font: { family: "Poppins", color: "#1E1B2E" } },
      topic: {
        title: { family: "Poppins", size: "16px", weight: "500", color: "#1E1B2E" },
        toggle: {
          trackColor: "#D9D3EC",
          trackActiveColor: "#8B5CF6",
          thumbColor: "#FFFFFF",
          borderRadius: "12px"
        }
      },
      digest: {
        font: { family: "Poppins", size: "14px", weight: "400", color: "#6B6580" },
        radio: { ringColor: "#D9D3EC", checkedColor: "#8B5CF6" }
      },
      channelChip: {
        font: { family: "Poppins", size: "14px", weight: "400", color: "#6B6580" },
        checkbox: { checkedColor: "#8B5CF6" }
      }
    });

    prefs.setMode("light");

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

Theme utilities are also exported: defaultLightTheme / defaultDarkTheme for the defaults, and mergeTheme(mode, overrideTheme) to merge a partial theme.

Show type CourierPreferencesTheme

type CourierPreferencesFontTheme = {
  family?: string;
  weight?: string;
  size?: string;
  color?: string;
};

type CourierPreferencesTheme = {
  primaryColor?: string;
  title?: CourierPreferencesFontTheme;
  subtitle?: CourierPreferencesFontTheme;
  container?: {
    font?: CourierPreferencesFontTheme;
  };
  loading?: {
    animation?: {
      barColor?: string;
      barHeight?: string;
      barBorderRadius?: string;
      duration?: string;
    };
  };
  error?: CourierPreferencesInfoStateTheme;
  empty?: CourierPreferencesInfoStateTheme;
  section?: {
    title?: CourierPreferencesFontTheme;
    backgroundColor?: string;
  };
  topic?: {
    backgroundColor?: string;
    border?: string;
    borderRadius?: string;
    title?: CourierPreferencesFontTheme;
    statusLabel?: CourierPreferencesFontTheme;
    toggle?: {
      trackColor?: string;
      trackActiveColor?: string;
      thumbColor?: string;
      borderRadius?: string;
    };
  };
  digest?: {
    font?: CourierPreferencesFontTheme;
    selectedFont?: CourierPreferencesFontTheme;
    iconColor?: string;
    radio?: {
      ringColor?: string;
      checkedColor?: string;
      font?: CourierPreferencesFontTheme;
      selectedFont?: CourierPreferencesFontTheme;
    };
  };
  channelChip?: {
    font?: CourierPreferencesFontTheme;
    selectedFont?: CourierPreferencesFontTheme;
    divider?: string;
    checkbox?: {
      checkedColor?: string;
      font?: CourierPreferencesFontTheme;
      selectedFont?: CourierPreferencesFontTheme;
    };
  };
};

// Title text, font, and button styling for the error and empty states.
type CourierPreferencesInfoStateTheme = {
  title?: {
    text?: string;
    font?: CourierPreferencesFontTheme;
  };
  button?: {
    text?: string;
    font?: CourierPreferencesFontTheme;
    backgroundColor?: string;
    hoverBackgroundColor?: string;
    border?: string;
    borderRadius?: string;
  };
};

Custom Channel Labels

Topics can be delivered over multiple channels. Use setChannelLabels() to rename how those channels appear in the UI.

index.html

<body>
  <courier-preferences id="prefs"></courier-preferences>

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

    const prefs = document.getElementById("prefs");

    prefs.setChannelLabels({
      email: "E-mail",
      push: "Mobile Push",
      sms: "Text Message"
    });

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

The default labels are:

Channel key	Default label
`direct_message`	Chat
`email`	Email
`push`	Push
`sms`	SMS
`webhook`	Webhook
`inbox`	Inbox

EU and regional endpoints

Only if your workspace uses the EU datacenter: pass EU URLs in Courier.shared.signIn. This package re-exports EU_COURIER_API_URLS and getCourierApiUrlsForRegion from @trycourier/courier-js.

import { EU_COURIER_API_URLS } from "@trycourier/courier-ui-inbox";

Courier.shared.signIn({
  userId: "my-user-id",
  jwt: "eyJ.mock.jwt",
  apiUrls: EU_COURIER_API_URLS,
});

See Courier JS — EU and regional endpoints for hostnames, helpers, and JWT issuance.

Client-side SDKs

Server-side SDKs

Courier Web Components SDK

Installation

Authentication

JWT Authentication Flow

Development Authentication with cURL

Inbox Web Components

`<courier-inbox>`

Tabs and Feeds

Handle Clicks and Presses

Styles and Theming

Custom Elements

Header Factory Props

Programmatic Control

Feed and Tab Selection

Header Actions

Static Helper Methods

Attribute vs Method Usage

Toast Web Components

`<courier-toast>`

HTML Attributes

Handle Clicks

Styles and Theming

Custom Elements

Programmatic Control

Toast Datastore

Preferences Web Components

`<courier-preferences>`

Preferences HTML Attributes

Preferences Styling and Theming

Custom Channel Labels

EU and regional endpoints

​Installation

​Authentication

​JWT Authentication Flow

​Development Authentication with cURL

​Inbox Web Components

​<courier-inbox>

​<courier-inbox-popup-menu>

​Tabs and Feeds

​Handle Clicks and Presses

​Styles and Theming

​Popup alignment, position, and dimensions

​Custom Elements

​Header Factory Props

​Programmatic Control

​Feed and Tab Selection

​Header Actions

​Popup Menu Control (on <courier-inbox-popup-menu>)

​Static Helper Methods

​Attribute vs Method Usage

​Toast Web Components

​<courier-toast>

​HTML Attributes

​Handle Clicks

​Styles and Theming

​Custom Elements

​Programmatic Control

​Toast Datastore

​Preferences Web Components

​<courier-preferences>

​Preferences HTML Attributes

​Preferences Styling and Theming

​Custom Channel Labels

​EU and regional endpoints

Installation

Authentication

JWT Authentication Flow

Development Authentication with cURL

Inbox Web Components

`<courier-inbox>`

`<courier-inbox-popup-menu>`

Tabs and Feeds

Handle Clicks and Presses

Styles and Theming

Popup alignment, position, and dimensions

Custom Elements

Header Factory Props

Programmatic Control

Feed and Tab Selection

Header Actions

Popup Menu Control (on `<courier-inbox-popup-menu>`)

Static Helper Methods

Attribute vs Method Usage

Toast Web Components

`<courier-toast>`

HTML Attributes

Handle Clicks

Styles and Theming

Custom Elements

Programmatic Control

Toast Datastore

Preferences Web Components

`<courier-preferences>`

Preferences HTML Attributes

Preferences Styling and Theming

Custom Channel Labels

EU and regional endpoints