Skip to main content
! Drop-in components for notifications in any JavaScript project:
  • <courier-inbox>: inbox for displaying and managing messages
  • <courier-inbox-popup-menu>: popup menu version of the inbox
  • <courier-toast>: toasts for time-sensitive alerts
  • <courier-preferences>: preferences center for topic subscriptions and delivery
This is the latest Courier Web Components SDK, for new and existing apps.Coming from an earlier version? Upgrade using the . The React SDK 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.
Available on GitHub and npm: Inbox · Inbox · Toast · Toast · Preferences · Preferences The Courier SDKs work with any JavaScript build system and need no extra build configuration.
Using React? The provides React components and hooks built on these Web Components.

Authentication

Courier authenticates with a JWT that your backend mints with your Courier API key, never in client code. covers the token flow, scope strings, reading auth state, signing out, token refresh, and EU-hosted workspaces.
Inbox and Toast share the same Courier.shared instance and socket connection. Authenticate once and both components work.

Inbox Web Components


<courier-inbox>

!

Default Courier Inbox component

Importing the Courier SDK registers Courier’s Web Components (<courier-inbox>, <courier-inbox-popup-menu>).
Sample App: See a complete working example in the Web Components example app.
If you’re using , you can scope requests to a particular tenant by passing its ID to the signIn request.
For the full reference of sign in parameters, see the .

<courier-inbox-popup-menu>

!

Default Courier Inbox Popup Menu component

Sample App: See a complete working example in the Web Components example app.

Tabs and feeds

The <courier-inbox> element takes feeds through setFeeds(), or a feeds attribute holding the same array as JSON. The concept, every filter field, and the datasetId uniqueness rule are on . selectFeed() and selectTab() pick one in code. See below.

Handle clicks and presses

Handle clicks and presses with onMessageClick(), onMessageActionClick(), and onMessageLongPress().
onMessageLongPress() is only applicable on devices that support touch events.

Styles and theming

Call setLightTheme() / setDarkTheme() with a CourierInboxTheme, or set the light-theme / dark-theme attributes to a JSON string of one. The object is identical on every web SDK, so every field is in . popup-alignment, popup-width, popup-height, and the top / right / bottom / left offsets position the panel. The nine alignment values and their defaults are in .

Custom elements

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

Programmatic control

<courier-inbox> exposes methods to manage feeds, tabs, actions, and data refresh at runtime.

Feed and tab selection

Header actions

Static helper methods


Attribute vs method usage

Most options can be set with HTML attributes or with methods:
  • HTML attributes: Best for initial, static configuration
  • Programmatic methods: Best for dynamic, runtime configuration
Some features are methods only and have no attribute: selectFeed(), refresh(), getFeeds().

Toast Web Components

Toasts are short-lived notifications that prompt users to act. The Toast component reads the Courier Inbox message feed.
Toasts sync with the Inbox message feed. Use both components together for persistent and temporary notifications.

<courier-toast>

Courier Toast component

Importing @trycourier/courier-ui-toast registers Courier’s Web Components (<courier-toast>).
Sample App: See a complete working example in the Web Components example app.

HTML attributes

Terminology: toast is the whole stack managed by <courier-toast>. A toast item is one toast shown for one message.

Toast component with auto-dismiss enabled.

With auto-dismiss set, the dismiss button (x) appears only on hover and each toast item dismisses itself. A countdown bar shows the time remaining.

Handle clicks

Courier Toast with action buttons

If a message contains , each toast item gets a button per action. These buttons do nothing until you wire them up.
index.html

Styles and theming

Call setLightTheme() / setDarkTheme() with a CourierToastTheme, or set light-theme / dark-theme to a JSON string of one. Every field, including the per-style action variants, is in . The theme has no toast wrapper. setLightTheme({ item: { ... } }) is the shape. An object nested under a toast key parses without error and applies nothing.

Custom elements


Programmatic control


Toast datastore

CourierToastDatastore holds the Inbox messages that <courier-toast> displays and dismisses. It is a singleton, accessed through CourierToastDatastore.shared.

Preferences Web Components

The Preferences component lets users manage their topic subscriptions inside your app. They also control how each topic is delivered, including per-channel routing and digest schedules.
Preferences ship in their own package, @trycourier/courier-ui-preferences (see Installation). It does not require the inbox or toast packages.

<courier-preferences>

Importing @trycourier/courier-ui-preferences registers the <courier-preferences> Web Component.
Preferences use the same authentication mechanism as the inbox, but the JWT must include the read:preferences and write:preferences scopes.

Preferences HTML attributes


Preferences styling and theming

Call setLightTheme() / setDarkTheme() with a CourierPreferencesTheme, or set light-theme / dark-theme to a JSON string of one. Setting primaryColor alone carries the accent through the toggles, radios, and chips. Every field is in .

Custom channel labels

Topics can be delivered over multiple channels. Use setChannelLabels() to rename those channels in the UI.
index.html
The default labels are:

EU and regional endpoints

Only needed if your workspace uses the . @trycourier/courier-ui-inbox re-exports EU_COURIER_API_URLS, DEFAULT_COURIER_API_URLS, and getCourierApiUrlsForRegion from @trycourier/courier-js. Pass the result as apiUrls on sign-in. For the hostnames, the helper semantics, and the same-region JWT requirement, see .

React SDK

React components and hooks built on the Web Components.

Inbox Theme Reference

The full CourierInboxTheme type definition for the inbox.