Courier Web Components SDK

The Web Components SDK ships Courier’s in-app components as standard custom elements, so they work in plain HTML or alongside any framework.

<courier-inbox>: 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>: preference center for topic subscriptions and delivery
CourierInboxDatastore and CourierToastDatastore: the data layer, for custom UIs

See these components in the interactive Inbox demo. No setup required.

Installation

The inbox, toast, and preferences are separate packages, so install only the ones you render.

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 packages have no peer dependencies and need no build configuration.

Using React, Vue, or Angular? The React, Vue, and Angular SDKs wrap these same elements as native components, with props and bindings in that framework’s idiom.

Authentication

Courier authenticates with a JWT that your backend mints with your Courier API key, never in client code. Authenticate users is the full guide: the token flow, scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See EU setup.

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

Courier.shared.signIn({ userId, jwt });  // also accepts tenantId, apiUrls, showLogs
Courier.shared.signOut();
Courier.shared.addAuthenticationListener(({ userId }) => { /* ... */ });

All three packages re-export the same Courier from @trycourier/courier-js. Import it from any one of them and sign in once, and every Courier element on the page uses that session and its real-time connection.

Quick start

Importing a package registers its elements, so the tag renders as soon as the module loads. Sign the user in and the inbox fills.

<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
    Courier.shared.signIn({
      userId: "user_123",
      jwt: jwt,
    });
  </script>
</body>

Follow the inbox guide for step-by-step guidance, including backend JWT generation. The Web Components example app wires up every element.

Component reference

Each component’s options, theme, callbacks, and custom-render surface live with the feature. These links open on the Web Components tab.

To do this	Go here
Embed the inbox, or render it as a popup	Add an inbox
Theme it, handle clicks, set its actions	Customize the inbox
Replace parts of it, or build your own	Build a custom inbox
Split it into filtered tabs and feeds	Tabs and feeds
Add toasts, and set auto-dismiss	Add toasts
Theme a toast or replace it	Customize toasts
Add a preference center	Add a preference center
Theme preferences, or build your own	Customize preferences
Send a message that reaches the inbox	Send to the inbox

The CourierInboxTheme, CourierToastTheme, and CourierPreferencesTheme objects are the same on React, Vue, Angular, and the Web Components, so each is documented once: inbox theme, toast theme, preferences theme.

Attributes and methods

Every option is an HTML attribute, a method on the element, or both. Attributes suit static setup written in markup. Methods suit anything that changes at runtime or takes a function, and they are what the framework SDKs call under the hood.

<!-- Attributes take strings, so a theme or feed list is a JSON string -->
<courier-inbox
  mode="light"
  light-theme='{"inbox": {"header": {"backgroundColor": "#FFFFFF"}}}'>
</courier-inbox>

<!-- Methods take objects and functions -->
<courier-inbox id="inbox"></courier-inbox>
<script type="module">
  const inbox = document.getElementById("inbox");

  inbox.setMode("light");
  inbox.setLightTheme({ inbox: { header: { backgroundColor: "#FFFFFF" } } });
</script>

Element	Attributes
`<courier-inbox>`	`height`, `feeds`, `mode`, `light-theme`, `dark-theme`, `message-click`, `message-action-click`, `message-long-press`
`<courier-inbox-popup-menu>`	`popup-alignment`, `popup-width`, `popup-height`, `top`, `right`, `bottom`, `left`, `feeds`, `mode`, `light-theme`, `dark-theme`
`<courier-toast>`	`auto-dismiss`, `auto-dismiss-timeout-ms`, `dismiss-button`, `mode`, `light-theme`, `dark-theme`
`<courier-preferences>`	`title`, `subtitle`, `brand-id`, `draft`, `mode`, `light-theme`, `dark-theme`

The inbox, the popup menu, and the preferences element also take preview, which renders injected data with no sign-in. Pair it with setPreviewData(). Render slots such as setListItem(), selectFeed(), refresh(), and the toast’s onToastItemClick() exist only as methods. Each one is documented on the In-App page for its feature. A theme attribute must be valid JSON. A malformed light-theme or dark-theme isn’t applied, and the inbox and toast throw a parse error to the console. Build the string with JSON.stringify(), or call setLightTheme() with the object instead. auto-dismiss turns off only when set to "false". Any other value, including an empty attribute, turns it on, and removing the attribute leaves it on. Call disableAutoDismiss() to turn it off from code.

Events

Besides its onMessage* methods, <courier-inbox> dispatches a DOM event for each interaction. The detail carries the same payload the method’s handler receives.

Event	`detail`
`message-click`	`{ message, index }`
`message-action-click`	`{ message, action, index }`
`message-long-press`	`{ message, index }`

document.addEventListener("message-click", (event) => {
  openInApp(event.detail.message);
});

The events bubble out of the element’s shadow DOM, so you can listen on the element, on <courier-inbox-popup-menu>, or on document. That suits a host that delegates events from one place, or that loads the element before its own code runs. The message-click, message-action-click, and message-long-press attributes take a function body as a string, the way onclick does, and run it with props in scope. The element compiles it with new Function, so a Content Security Policy without 'unsafe-eval' blocks it. Use the event or the method under a strict CSP.

Typing the elements

Each package exports its element class, so a TypeScript host can type the element it queries and get the methods autocompleted.

import { CourierInbox } from "@trycourier/courier-ui-inbox";
import type { CourierToast } from "@trycourier/courier-ui-toast";
import type { CourierPreferences } from "@trycourier/courier-ui-preferences";

const inbox = document.getElementById("inbox") as CourierInbox;
inbox.setFeeds(CourierInbox.defaultFeeds());

Advanced

Server-side rendering

Importing a package on the server is safe. The elements register only when window exists, so the import is a no-op under Node, and the tags render once the module runs in the browser. In Next.js, import the package from a client component.

Troubleshooting

The element renders nothing

The package isn’t imported on that page, so the browser treats the tag as an unknown element. Import the package (@trycourier/courier-ui-inbox for the inbox) in a module that runs on that page.

A method call throws 'is not a function'

The script ran before the element was registered. Import the package first, or wait with await customElements.whenDefined("courier-inbox") before calling methods.

Messages not loading

Possible causes:

Not authenticated: call Courier.shared.signIn()
JWT expired: generate a new token
Missing scopes: include inbox:read:messages and inbox:write:events in the JWT
Wrong user ID: the userId must match the user the JWT was issued for

Get started

Server

Client

Courier Web Components SDK

Installation

Authentication

Quick start

Component reference

Attributes and methods

Events

Typing the elements

Advanced

Server-side rendering

Troubleshooting

​Installation

​Authentication

​Quick start

​Component reference

​Attributes and methods

​Events

​Typing the elements

​Advanced

​Server-side rendering

​Troubleshooting

Installation

Authentication

Quick start

Component reference

Attributes and methods

Events

Typing the elements

Advanced

Server-side rendering

Troubleshooting