Embed a customizable in-app notification center and toasts in your React app. Courier React components seamlessly integrate with email, SMS, push, and more.
Available on
GitHub
and npm.Courier publishes two React packages: @trycourier/courier-react for React 18+ and @trycourier/courier-react-17 for React 17.
Copy
Ask AI
npm install @trycourier/courier-react
This is the latest version of the Courier React SDK, recommended for new and existing apps.If you’re coming from an earlier version of the Courier React SDK, check out the
v8 migration guide for what’s changed,
how to upgrade your app, and links to documentation for past versions of the React SDK.
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.
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).
Get up and running with Courier React in minutes. This minimal example shows how to add the inbox component to your app.
Copy
Ask AI
"use client"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: $YOUR_USER_ID, jwt: jwt, }); }, []); return <CourierInbox />;}
type InboxMessage = { messageId: string; title?: string; body?: string; read?: string; // ISO timestamp when message was read opened?: string; // ISO timestamp when message was opened archived?: string; // ISO timestamp when message was archived tags?: string[]; trackingIds?: { clickTrackingId?: string; openTrackingId?: string; }; actions?: InboxAction[]; data?: Record<string, unknown>; // ... other properties}
Represents a dataset of messages with pagination information. This is the structure returned by inbox.feeds[datasetId] and inbox.fetchNextPageOfMessages().
Show type InboxDataSet
Copy
Ask AI
type InboxDataSet = { /** The unique identifier for this dataset (matches the tab's datasetId) */ id: string; /** Array of messages in this dataset */ messages: InboxMessage[]; /** Number of unread messages in this dataset */ unreadCount: number; /** Whether more pages of messages are available */ canPaginate: boolean; /** Cursor for fetching the next page (null if no more pages) */ paginationCursor: string | null;}
type CourierInboxFeed = { /** Unique identifier for this feed */ feedId: string; /** Display name for the feed */ title: string; /** Optional SVG icon for the feed */ iconSVG?: string; /** Tabs that belong to this feed */ tabs: CourierInboxTab[];}
type CourierInboxTab = { /** Unique identifier linking this tab to its dataset */ datasetId: string; /** Display name for the tab */ title: string; /** Message filters to apply to this tab */ filter: CourierInboxDatasetFilter;}
Defines filters for messages. Filters are combined with AND logic, meaning all specified conditions must be met.
Show type CourierInboxDatasetFilter
Copy
Ask AI
type CourierInboxDatasetFilter = { /** * Messages that have any of the specified tags. * If a message has any tag in this array, it will be included. */ tags?: string[]; /** * Whether to include archived messages. * Defaults to `false` if unset (only unarchived messages). * Set to `true` to include archived messages. */ archived?: boolean; /** * Filter by read/unread status. * - `'read'`: Only show read messages * - `'unread'`: Only show unread messages * - `undefined`: Show both read and unread messages */ status?: 'read' | 'unread';}
Filter Logic: All filter properties are AND’d together. For example:
{ tags: ['important'], status: 'unread' } shows messages that have the ‘important’ tag AND are unread
{ archived: true, status: 'read' } shows messages that are archived AND read
Props passed to custom toast item render functions.
Show type CourierToastItemFactoryProps
Copy
Ask AI
type CourierToastItemFactoryProps = { /** The message for which the toast item is being created */ message: InboxMessage; /** Whether the toast item will auto-dismiss */ autoDismiss: boolean; /** The timeout before auto-dismissal in milliseconds */ autoDismissTimeoutMs: number; /** Function to manually dismiss the toast */ dismiss: () => void;}
