Courier React SDK

The React SDK wraps Courier’s in-app components as React components, plus one hook that exposes the client behind them.

<CourierInbox /> and <CourierInboxPopupMenu />, an inbox as a panel or a popup
<CourierToast />, toasts for messages that arrive while the app is open
<CourierPreferences />, a preference center for topic subscriptions
useCourier(), the client, for custom UIs and for driving the components from outside

The components behave identically on every web framework, so this page doesn’t repeat their reference. Install and sign in here, then follow for what each component does. Every code sample there has a React tab.

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

Installation

Available on GitHub and npm. Courier publishes two React packages: @trycourier/courier-react for React 18+ and @trycourier/courier-react-17 for React 17.

npm install @trycourier/courier-react

npm install @trycourier/courier-react-17

This is the latest version of the Courier React SDK, recommended for new and existing apps.Coming from an earlier version? The covers what changed, how to upgrade, and docs for past versions.

Not using React? Use the and packages instead. They provide Web Components for any JavaScript project.

Authentication

Courier authenticates with a JWT that your backend mints with your Courier API key, never in client code. is the full guide: the token flow, scope strings, reading auth state, signing out, token refresh, and EU-hosted workspaces.

const { auth } = useCourier();

auth.signIn({ userId, jwt });  // also accepts tenantId, apiUrls, showLogs
auth.signOut();
auth.userId;                   // undefined when signed out

Quick start

Add the inbox component to your app.

import { useEffect } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    courier.shared.signIn({
      userId: "user_123",
      jwt: jwt,
    });
  }, []);

  return <CourierInbox />;
}

import { useEffect } from "react";
import { CourierInbox, useCourier } from "@trycourier/courier-react-17";

export default function App() {
  const courier = useCourier();

  useEffect(() => {
    // Generate a JWT for your user on your backend server
    const jwt = "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...";

    // Authenticate the user
    courier.shared.signIn({
      userId: "user_123",
      jwt: jwt,
    });
  }, []);

  return <CourierInbox />;
}

Scope requests to one by passing its ID to signIn:

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

Component reference

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

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

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

useCourier hook

useCourier() returns the Courier client and the three component surfaces. Use it to build your own UI, or to drive a prebuilt component from outside it.

const { shared, auth, inbox, toast, preferences } = useCourier();

Key	What it holds	Reference
`shared`	The `Courier` client itself, for anything the keys below don’t cover.
`auth`	`signIn`, `signOut`, and `userId`.
`inbox`	`feeds`, `totalUnreadCount`, `error`, and every message action.
`toast`	`addMessage` and `removeMessage`, to push a toast yourself.
`preferences`	Read and write a user’s topics, routing, and digest schedule.

Components and the hook aren’t a choice between two integrations. The components call the same client the hook returns, so a page can render <CourierInbox /> and read inbox.totalUnreadCount for a badge elsewhere in the same tree. Call inbox.listenForUpdates() after you authenticate. It opens the realtime connection, which nothing else in a custom UI calls for you. Without it, the inbox loads once and doesn’t update again.

await auth.signIn({ userId, jwt });
inbox.registerFeeds(feeds);
await inbox.listenForUpdates();
await inbox.load();

Advanced

Next.js and SSR

Courier Inbox and Toast support Next.js but render client-side only. In Next.js 13+, add 'use client' to the top of any file using Courier components.

"use client"

import { CourierInbox } from "@trycourier/courier-react";

export default function Page() {
  // Authentication code...
  return <CourierInbox />;
}

Troubleshooting

Inbox not updating in real-time

Call inbox.listenForUpdates() after authentication. It opens the WebSocket connection required for real-time updates.

await auth.signIn({ userId, jwt });
inbox.registerFeeds(defaultFeeds());
await inbox.listenForUpdates(); // Required for real-time
await inbox.load();

Messages not loading

Possible causes:

Not authenticated: call signIn()
Feeds not registered: call registerFeeds() before load()
Network errors: check inbox.error for details
JWT expired: generate a new token

Authentication errors

Invalid JWT: generate the JWT correctly on your backend
Expired JWT: JWTs expire. Generate a new one
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

Two tabs show identical messages

Two tabs sharing a datasetId collapse into one dataset. Every datasetId has to be unique across all feeds, not only within one. See .

TypeScript errors

Import types directly from the package:

import { useCourier, type InboxMessage, type CourierInboxFeed } from '@trycourier/courier-react';

React 17 vs React 18 package mismatch

Use the correct package:

React 18+: @trycourier/courier-react
React 17: @trycourier/courier-react-17

Best practices

JWT security: always generate JWTs server-side. Cache on the client, refresh before expiration (standard: '1d'), and include only the scopes you need.
Performance: canUseCache: true (default) serves cached data. Use datasetIds to load only the datasets you need, and set a suitable setPaginationLimit(). The hook’s reactive state updates on its own, so avoid unnecessary re-renders.
Testing: mock useCourier() in tests to return test data:

jest.mock('@trycourier/courier-react', () => ({
  useCourier: () => ({
    inbox: {
      feeds: { 'all_messages': { messages: mockMessages } },
      totalUnreadCount: 5
    }
  })
}));

EU and regional endpoints

Only needed if your workspace uses the . @trycourier/courier-react 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 .

TypeScript types

Show type InboxMessage

type InboxMessage = {
  messageId: string;
  title?: string;
  body?: string;
  read?: string;     // ISO timestamp
  opened?: string;   // ISO timestamp
  archived?: string; // ISO timestamp
  tags?: string[];
  trackingIds?: { clickTrackingId?: string; openTrackingId?: string; };
  actions?: InboxAction[];
  data?: Record<string, unknown>;
}

Show type InboxDataSet

type InboxDataSet = {
  id: string;
  messages: InboxMessage[];
  unreadCount: number;
  canPaginate: boolean;
  paginationCursor: string | null;
}

Show type CourierInboxFeed

type CourierInboxFeed = {
  feedId: string;
  title: string;
  iconSVG?: string;
  tabs: CourierInboxTab[];
}

Show type CourierInboxTab

type CourierInboxTab = {
  datasetId: string;
  title: string;
  filter: CourierInboxDatasetFilter;
}

Show type CourierInboxDatasetFilter

type CourierInboxDatasetFilter = {
  tags?: string[];
  archived?: boolean;
  status?: 'read' | 'unread';
  from?: string;   // ISO 8601, lower bound on creation time
}

Set fields are AND’d together, while several tags match as OR. { tags: ['important'], status: 'unread' } shows unread messages tagged important. has each field.

Show type CourierToastItemFactoryProps

type CourierToastItemFactoryProps = {
  message: InboxMessage;
  autoDismiss: boolean;
  autoDismissTimeoutMs: number;
  dismiss: () => void;
}

Get started

Server

Client

Courier React SDK

Installation

Authentication

Quick start

Component reference

useCourier hook

Advanced

Next.js and SSR

Troubleshooting

Best practices

EU and regional endpoints

TypeScript types

​Installation

​Authentication

​Quick start

​Component reference

​useCourier hook

​Advanced

​Next.js and SSR

​Troubleshooting

​Best practices

​EU and regional endpoints

​TypeScript types

Installation

Authentication

Quick start

Component reference

useCourier hook

Advanced

Next.js and SSR

Troubleshooting

Best practices

EU and regional endpoints

TypeScript types