Courier React v8 migration guide

What’s new in React v8+

v8+ is a major update to Courier’s web SDKs. It brings:

A redesigned UI with built-in dark mode
Themeable components
A smaller JavaScript bundle with no third-party dependencies

Pins aren’t yet supported in v8+. A message can’t be pinned to the top of the inbox. If your app needs them, stay on v7 for now.Tags carry over, but the model changed. v7 added and removed a message’s tags from the client. In v8+ a tag is a read filter: you set tags on the send, and a tab shows the messages carrying them.

What’s in this guide

Migration steps for:

Courier Inbox components
Courier Toast components
Courier Preferences components

All three share the same first steps: upgrade dependencies and authentication. After those, skip to Toasts or Preferences if you have no Inbox components to migrate.

Migration steps

1. Upgrade dependencies

v8+ ships as one package: @trycourier/courier-react for React 18+, or @trycourier/courier-react-17 for React 17. The two are identical. The examples below work with either, and your app should install only one. Earlier Courier React SDKs required several packages, such as @trycourier/react-provider and @trycourier/react-inbox. Remove them as part of this migration.

npm install --save @trycourier/courier-react

npm install --save @trycourier/courier-react-17

In your app’s package.json, remove existing @trycourier React dependencies:

{
  "dependencies": {
    "@trycourier/react-provider": "^7.4.0", 
    "@trycourier/react-inbox": "^7.4.0", 
    "@trycourier/react-toast": "^7.4.0", 
    "@trycourier/courier-react": "^8.2.0", 
    "react": "^19.1.1",
    "react-dom": "^19.1.1"
  }
}

{
  "dependencies": {
    "@trycourier/react-provider": "^7.4.0", 
    "@trycourier/react-inbox": "^7.4.0", 
    "@trycourier/react-toast": "^7.4.0", 
    "@trycourier/courier-react-17": "^8.2.0", 
    "react": "^17.0.2",
    "react-dom": "^17.0.2"
  }
}

2. Generate JWTs

Already generating JWTs (JSON Web Tokens) for Courier SDKs? Skip this step.

Earlier Courier React SDKs accepted client keys: a stable, Base64 encoded identifier, with or without an HMAC signature. v8+ replaces them with JWTs, short-lived signed tokens your backend mints with your Courier API key. Client keys no longer authenticate anything, so every app needs a backend endpoint that issues a token. covers minting the token, the scope strings, reading auth state, signing out, and token refresh. Using the EU datacenter? See . Inbox and Toast components need the three required scopes in . Migrating Preferences components too? Add read:preferences and write:preferences.

3. Authenticate the Courier SDK

Replace every <CourierProvider> with one call to courier.shared.signIn(). That method lives on the singleton useCourier() returns. covers signOut and token refresh.

The Courier SDK shares authentication between components, so one call to courier.shared.signIn is enough.Using only Courier toasts? Skip to Upgrade Toast components for the <CourierToast> version of this example.

App.tsx

import { CourierProvider } from "@trycourier/react-provider"; 
import { Inbox } from "@trycourier/react-inbox"; 
import { useEffect, useState } from "react"; 
import { CourierInbox, useCourier } from "@trycourier/courier-react"; 

function App() {
  const [courierJwt, setCourierJwt] = useState<string>();
  const courier = useCourier(); 

  const generateCourierJwt = async () => {
    // Call your backend to generate a JWT
    setCourierJwt(result);
  };

  // When the userId in the app changes,
  // generate a new JWT to sign in to the Courier SDK
  useEffect(() => {
    generateCourierJwt();
  }, [userId]);

  // When courierJwt has been updated, call signIn
  useEffect(() => { 
    // Authenticate the user with the inbox
    courier.shared.signIn({ userId, jwt: courierJwt }); 
  }, [courierJwt]); 

  return (
    <CourierProvider
      authentication={courierJwt}
      clientKey={clientKey}>
      <Inbox />
    </CourierProvider>
    <CourierInbox />
  );
}

4. Upgrade Inbox components

4a. Theming

v8+ drops styled-components and themes natively. The theme definition changed. Compare the v7 theme with the types.

App.tsx

import { Inbox } from "@trycourier/react-inbox"; 
import { CourierProvider } from "@trycourier/react-provider"; 
import { CourierInbox, CourierInboxTheme } from "@trycourier/courier-react"; 

function App() {
  // `CourierInboxTheme` is exposed in `@trycourier/courier-react` and may provide
  // helpful hints in your code editor.
  const theme: CourierInboxTheme = {
    // In v8+, inbox theme values are nested under `inbox`
    inbox: { 
      header: {
        background: "#0f0f0f", 
        backgroundColor: "#0f0f0f"
      },

      messageList: { 
        container: { 
          background: "red", 
        }, 
      }, 
      list: { 
        backgroundColor: "red", 
      }, 

      item: { 
        backgroundColor: "purple", 
        hoverBackgroundColor: "steelblue", 
      }, 
    }, 

    // In v8+, message theme values are nested under `inbox.item`
    message: { 
      container: { 
        background: "purple", 
      }, 
      "&:hover": { 
        background: "steelblue", 
      }, 
    }, 

    // The Courier watermark is removed in v8+,
    // so footer theming is no longer applicable
    footer: { 
      background: "pink", 
    }, 
  };

  return (
    <CourierProvider>
      <Inbox theme={theme} />
    </CourierProvider>
    <CourierInbox lightTheme={theme} darkTheme={theme} mode="light" />
  );
}

Dark mode

React Inbox v8+ switches between light and dark mode automatically, following system preferences.

App.tsx

import { Inbox } from "@trycourier/react-inbox"; 
import { CourierProvider } from "@trycourier/react-provider"; 
import { CourierInbox, CourierInboxTheme } from "@trycourier/courier-react"; 
import { appTheme } from "./theme";

function App() {
  // In v8+, the entire dark mode theme can be customized
  const darkThemeVariables = { 
    background: "black", 
  }; 

  const lightTheme: CourierInboxTheme = { 
    ...appTheme, 
    // Light mode overrides...
  }; 

  const darkTheme: CourierInboxTheme = { 
    ...appTheme, 
    // Dark mode overrides...
  }; 

  return (
    <CourierProvider theme={{ colorMode: "dark", variables: darkThemeVariables }}>
      <Inbox theme={darkTheme} />
    </CourierProvider>

    // In v8+, themes can be set for both light and dark mode
    // Use the `mode` prop to force the "light", "dark", or "system" color mode
    <CourierInbox lightTheme={lightTheme} darkTheme={darkTheme} mode="system" />
  );
}

4b. Custom components

You can override most components in the default UI. Some prop names and method signatures for passing components changed in v8+. See and .

App.tsx

import { Inbox } from "@trycourier/react-inbox"; 
import { CourierProvider } from "@trycourier/react-provider"; 
import { 
  CourierInbox, 
  type CourierInboxHeaderFactoryProps, 
  type CourierInboxListItemFactoryProps
} from '@trycourier/courier-react'; 

export default function App() {
  const CustomHeader = (props: CourierInboxHeaderFactoryProps) => { 
    const selectedFeed = props.feeds.find(feed => feed.isSelected); 
    const selectedTab = selectedFeed?.tabs.find(tab => tab.isSelected); 
    return ( 
      <div style={{ 
        background: "red", 
        fontSize: "24px", 
        padding: "24px", 
        width: "100%"
      }}>
        {selectedFeed?.title ?? 'No feed selected'} | {selectedTab?.title ?? 'No tab selected'}
      </div>
    ); 
  }; 

  const CustomListItem = (
    // In v8+, the full message and its index within the inbox are available
    message => ( 
    { message, index }: CourierInboxListItemFactoryProps) => ( 
      <pre style={{
        padding: '24px',
        borderBottom: '1px solid #e0e0e0',
        margin: '0'
      }}>
        {JSON.stringify({ message }, null, 2)}
      </pre>
    );

  return (
    <CourierProvider>
      <Inbox renderMessage={(props) => { 
        return <CustomListItem {...props} />
      }} />
    </CourierProvider>
    <CourierInbox
      renderHeader={(props: CourierInboxHeaderFactoryProps) => { 
        if (!props) return null; 
        return <CustomHeader {...props} />; 
      }}
      renderListItem={(props: CourierInboxListItemFactoryProps) => { 
        return <CustomListItem {...props} />
      }}
    />
  );
}

Custom component prop changes

Inbox components:

v7 prop	v8+ prop
`renderMessage`	`renderListItem`
`renderNoMessages`	`renderEmptyState`
`renderHeader`	`renderHeader`
New in v8+	`renderLoadingState`
New in v8+	`renderErrorState`
New in v8+	`renderPaginationItem`
`renderPin`	Pins aren’t yet supported in v8+
`renderFooter`	The Courier watermark footer is removed in v8+.

In v8+, renderHeader receives CourierInboxHeaderFactoryProps, which holds a feeds array, not feedType. Each feed has feedId, title, iconSVG, tabs, and isSelected.

4c. React hooks

Pins aren’t yet supported in v8+, and neither is changing a message’s tags from the client. Reading and filtering by tag both work, through feeds and tabs.

A custom UI fetches messages and holds inbox state itself, with hooks. Courier’s React hooks now ship inside @trycourier/courier-react. Remove any dependency on @trycourier/react-hooks.

package.json

{
  "dependencies": {
    "@trycourier/react-hooks": "^7.4.0", 
    "@trycourier/courier-react": "^8.0.28"
  }
}

Change useInbox() to useCourier() and update the changed method signatures. The full set of updated hooks follows.

App.tsx

import { useInbox } from "@trycourier/react-hooks"; 
import { useCourier, type CourierInboxFeed } from "@trycourier/courier-react"; 

const MyCustomInbox = () => {
  const inbox = useInbox(); 
  const { inbox } = useCourier(); 

  useEffect(() => {
    // Register feeds (new in v8+)
    const feeds: CourierInboxFeed[] = [ 
      { 
        feedId: 'inbox', 
        title: 'Inbox', 
        tabs: [{ datasetId: 'all_messages', title: 'All', filter: {} }] 
      } 
    ]; 
    inbox.registerFeeds(feeds); 

    // Set up socket listener for real-time updates (new in v8+)
    await inbox.listenForUpdates(); 

    inbox.fetchMessages(); 
    await inbox.load(); 
  }, []);

  const handleRead = (message) => (event) => {
    event.preventDefault();

    inbox.markMessageRead(message.messageId); 
    inbox.readMessage({ message }); 
  };

  const handleUnread = (message) => (event) => {
    event.preventDefault();

    inbox.markMessageUnread(message.messageId); 
    inbox.unreadMessage(message) 
  };

  const handleArchive = (message) => (event) => {
    event.preventDefault();

    inbox.markMessageArchived(message.messageId); 
    inbox.archiveMessage(message); 
  };

  // Access messages by datasetId (new in v8+)
  const messages = inbox.feeds['all_messages']?.messages || []; 

  return (
    <Container>
      {inbox.messages.map((message) => { 
      {messages.map((message) => { 
        return (
          <Message message={message}>
            {message.read ? (
              <>
                <button onClick={handleUnread(message)}>Mark Unread</button>
                <button onClick={handleArchive(message)}>Archive</button>
              </>
            ) : (
              <button onClick={handleRead(message)}>Mark Read</button>
            )}
          </Message>
        );
      })}
    </Container>
  )
}

Method signature changes

v7 signature	v8+ signature
`fetchMessages()`	`load()`
New in v8+	`setPaginationLimit(limit: number)`
`fetchNextPageOfMessages({ feedType: 'inbox' \| 'archive' })`	`fetchNextPageOfMessages({ datasetId: string })` Note: `feedType` is deprecated, use `datasetId`
`getUnreadMessageCount()`	Replaced with `load()` (async, refresh the inbox) and `inbox.totalUnreadCount` (sync, reads stored state)
`markMessageRead(messageId: string)`	`readMessage(message: InboxMessage)`
`markMessageUnread(messageId: string)`	`unreadMessage(message: InboxMessage)`
`markMessageArchived(messageId: string)`	`archiveMessage(message: InboxMessage)`
New in v8+	`unarchiveMessage(message: InboxMessage)`
`trackClick(messageId: string, trackingId: string)`	`clickMessage(message: InboxMessage)`
`markMessageOpened(messageId: string)`	`openMessage(message: InboxMessage)`
`markAllAsRead()`	`readAllMessages()`
New in v8+	`registerFeeds(feeds: CourierInboxFeed[])`
New in v8+	`listenForUpdates()`
`inbox.messages`	`inbox.feeds[datasetId].messages` Access messages by datasetId instead of a single array
`addTag(messageId: string, tag: string)`	No client-side equivalent. Set a message’s tags on the send, then filter on them with `registerFeeds()`
`removeTag(messageId: string, tag: string)`	No client-side equivalent. A tag is fixed once the message is sent
`unpinMessage(messageId: string)`	Not yet supported in v8+

4d. Feeds and tabs

v8+ adds feeds and tabs for organizing messages. A feed groups related tabs. Each tab is a filtered view of messages within its feed.

Feeds group tabs into sections, such as Inbox, Archive, and Notifications.
Tabs filter the messages in a feed, such as All, Unread, and Important.
Datasets back each tab, identified by a unique datasetId.

A tab’s filter takes tags, status, archived, and from. Set fields are AND’d together, while several tags match as OR. This is where v7’s message tags land: send a message with its tags, then give each tag a tab. For every field, see the . Pass a feeds prop to <CourierInbox> to configure feeds and tabs:

App.tsx

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

function App() {
  const feeds: CourierInboxFeed[] = [ 
    { 
      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'] } 
        } 
      ] 
    } 
  ]; 

  return (
    <CourierInbox feeds={feeds} />
  );
}

With hooks, register feeds with inbox.registerFeeds() and access messages by datasetId:

App.tsx

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

const MyCustomInbox = () => {
  const { inbox } = useCourier();

  useEffect(() => {
    const feeds: CourierInboxFeed[] = [ 
      { 
        feedId: 'inbox', 
        title: 'Inbox', 
        tabs: [{ datasetId: 'all_messages', title: 'All', filter: {} }] 
      } 
    ]; 

    // Register feeds (new in v8+)
    inbox.registerFeeds(feeds); 

    // Set up socket listener for real-time updates (new in v8+)
    await inbox.listenForUpdates(); 

    // Load the inbox
    await inbox.load();
  }, []);

  // Access messages by datasetId (new in v8+)
  const messages = inbox.feeds['all_messages']?.messages || []; 

  return (
    <Container>
      {messages.map((message) => { 
        return (
          <Message message={message}>
            {/* ... */}
          </Message>
        );
      })}
    </Container>
  )
}

In v7, messages were accessed through inbox.messages. In v8+:

Messages are organized by datasetId in inbox.feeds[datasetId].messages
Use inbox.registerFeeds() to configure feeds and tabs
Use inbox.listenForUpdates() to enable real-time updates
Use datasetId (not feedType) when calling fetchNextPageOfMessages()

The has the rest.

5. Upgrade Toast components

v8+ includes a redesigned Toast component with more customization, native theming, and dark mode. Migrating from v7 Toast means updating the component usage, its props, and the theme structure. Replace every <CourierProvider> with one call to courier.shared.signIn(). That method lives on the singleton useCourier() returns.

Already authenticated for Courier Inbox? Replace each <CourierProvider>...</CourierProvider> block with <CourierToast>.The Courier SDK shares authentication between components, so one call to courier.shared.signIn is enough.

App.tsx

import { CourierProvider } from "@trycourier/react-provider"; 
import { Toast } from "@trycourier/react-toast"; 
import { useEffect, useState } from 'react'; 
import { CourierToast, useCourier } from "@trycourier/courier-react"; 

function App() {
  const [courierJwt, setCourierJwt] = useState<string>();
  const courier = useCourier(); 

  const generateCourierJwt = async () => {
    // Call your backend to generate a JWT
    setCourierJwt(result);
  };

  // When the userId in the app changes,
  // generate a new JWT to sign in to the Courier SDK
  useEffect(() => {
    generateCourierJwt();
  }, [userId]);

  // When courierJwt has been updated, call signIn
  useEffect(() => { 
    // Authenticate the user
    courier.shared.signIn({ userId, jwt: courierJwt }); 
  }, [courierJwt]); 

  return (
    <CourierProvider
      authentication={courierJwt}
      clientKey={clientKey}>
      <Toast />
    </CourierProvider>
    <CourierToast />
  );
}

5a. Toast props

Some <CourierToast> props changed or moved in v8+, alongside new props for theming, custom components, and user interaction.

v7	v8+	Notes
`autoClose`	`autoDismiss` and `autoDismissTimeoutMs`	In v8+, split into two separate props. `autoDismiss` is a boolean
`defaultIcon`	Removed in v8+	In v8+, configured via theme object. See theming below
`hideProgressBar`	`autoDismiss`	In v8+, progress bar only displays when `autoDismiss` is enabled
New in v8+	`dismissButton`	Display option for the dismiss button
`onClick`	`onToastItemClick`	Event signature has changed in v8+
New in v8+	`onToastItemActionClick`	Handle an action button click
`position`	`style`	Use React’s CSS-like `style` prop on `<CourierToast>`
`theme`	`lightTheme` and `darkTheme`	v8+ introduces separate themes for light and dark modes
`transition`	Removed in v8+	Configure custom transitions by implementing `renderToastItem`
`role`	Not yet supported in v8+
New in v8+	`renderToastItemContent`	Customize the toast item content area. See custom components below
New in v8+	`renderToastItem`	Completely customize the toast items and stack. See custom components below

5b. Theming

v8+ drops the styled-components package and themes natively. The theme definition changed. Compare the v7 theme with the types.

App.tsx

import { Toast } from "@trycourier/react-toast"; 
import { CourierProvider } from "@trycourier/react-provider"; 
import { CourierToast, CourierToastTheme } from "@trycourier/courier-react"; 

function App() {
  // `CourierToastTheme` is exposed in `@trycourier/courier-react`
  // and may provide helpful hints in your code editor.
  const theme: CourierToastTheme = {
    // Styles applied to the top-level container (ex. z-index or position)
    // In v8+ these are applied with the `style` prop on <CourierToast>
    root: { 
      top: "10px", 
      right: "10px", 
    }, 

    // Styles for toast items' outer container
    // In v8+ this is configurable under `item`
    toast: {} 

    // Styles for message contents
    // In v8+ these are nested as values under `item`
    message: { 
      container: { background: "white" }, 
      title: { color: "black" } 
    }, 

    // Styles for the progress bar
    // In v8+ this is nested under `item.autoDismissBarColor`
    progressBar: { 
      background: "purple"
    }, 

    item: { 
      backgroundColor: "white", 
      title: { 
        color: "black"
      }, 
      autoDismissBarColor: "purple"
    }, 
  };

  return (
    <CourierProvider>
      <Toast theme={theme} />
    </CourierProvider>
    <CourierToast
      lightTheme={theme}
      darkTheme={theme}
      style={{ top: "10px", right: "10px" }} />
  );
}

Dark mode

React Toast v8+ themes dark mode fully and switches between light and dark automatically, following system preferences. Every field is in the type.

App.tsx

import { Toast } from "@trycourier/react-toast"; 
import { CourierProvider } from "@trycourier/react-provider"; 
import { CourierToast, CourierToastTheme } from "@trycourier/courier-react"; 
import { appTheme } from "./theme";

function App() {
  const lightTheme: CourierToastTheme = { 
    ...appTheme, 
    // Light mode overrides...
  }; 

  const darkTheme: CourierToastTheme = { 
    ...appTheme, 
    // Dark mode overrides...
  }; 

  return (
    <CourierProvider>
      <Toast theme={darkTheme} />
    </CourierProvider>

    // In v8+, themes can be set for both light and dark mode
    // Use the `mode` prop to force the "light", "dark", or "system" color mode
    <CourierToast lightTheme={lightTheme} darkTheme={darkTheme} mode="system" />
  );
}

5c. Custom components

For customization beyond theming, v8+ adds two render props:

renderToastItemContent: Customize the content area, keeping the default styles, animations, and dismiss behavior.
renderToastItem: Replace the appearance and behavior of the toast items and stack.

See and .

5d. React hooks

A custom UI holds toast state itself, with hooks. Courier’s React hooks now ship inside @trycourier/courier-react. Remove any dependency on @trycourier/react-hooks.

package.json

{
  "dependencies": {
    "@trycourier/react-hooks": "^7.4.0", 
    "@trycourier/courier-react": "^8.0.28"
  }
}

Change useToast() to useCourier() and update the changed method signatures. The full set of updated hooks follows.

App.tsx

import { useToast } from "@trycourier/react-hooks"; 
import { useCourier } from "@trycourier/courier-react"; 

const MyCustomToast = () => {
  const [toast] = useToast(); 
  const { toast } = useCourier(); 

  useEffect(() => {
    toast({ 
    toast.addMessage({ 
      title: "Hello, world!", 
      preview: "This is a toast."
    }); 
  }, [])

  return (
    <CourierToast
      onToastItemClick={({ message }) => { 
        // New in v8+
        toast.removeMessage(message); 
      }}
    />
  );
}

Method signature changes

v7 signature	v8+ signature
`toast(message)`	`toast.addMessage(message: InboxMessage)`
New in v8+	`toast.removeMessage(message: InboxMessage)`

config and clientKey info are removed from hooks in v8+.

6. Upgrade Preferences components

v8+ replaces the v7 <PreferencesV4> component, from @trycourier/react-preferences, with <CourierPreferences>. It shares the redesigned UI, native theming, and dark mode of the other v8+ components. As with Inbox and Toast, replace <CourierProvider> with one call to courier.shared.signIn(). Already authenticated for another v8+ component? No second sign-in is needed. The SDK shares authentication across components.

Preferences requires a JWT with the read:preferences and write:preferences scopes.

App.tsx

import { CourierProvider } from "@trycourier/react-provider"; 
import { PreferencesV4 } from "@trycourier/react-preferences"; 
import { useEffect, useState } from 'react'; 
import { CourierPreferences, useCourier } from "@trycourier/courier-react"; 

function App() {
  const [courierJwt, setCourierJwt] = useState<string>();
  const courier = useCourier(); 

  // When courierJwt has been updated, call signIn
  useEffect(() => { 
    courier.shared.signIn({ userId, jwt: courierJwt }); 
  }, [courierJwt]); 

  return (
    <CourierProvider
      authentication={courierJwt}
      clientKey={clientKey}>
      <PreferencesV4 />
    </CourierProvider>
    <CourierPreferences />
  );
}

6a. Preferences props

The v7 <PreferencesV4> component accepted only two props, tenantId and draft. It had no theming props. Its colors came from the brand configured on the fetched preference page. Three things change in v8+:

Tenant scoping moves to signIn. There is no per-component prop.
Draft-preview isn’t yet available.
<CourierPreferences> adds native client-side theming and other options.

v7	v8+	Notes
`tenantId`	Set via `signIn`	Tenant scoping is set once at authentication with `courier.shared.signIn({ userId, jwt, tenantId })` rather than per component. It applies to both `<CourierPreferences>` and the headless `useCourier().preferences` hooks
`draft`	Not yet available	Draft-preview isn’t yet supported by `<CourierPreferences>` in v8+. If you depend on it, remain on v7 for now
New in v8+	`lightTheme` / `darkTheme`	Native theming for light and dark modes (see Theming)
New in v8+	`mode`	Force the `"light"`, `"dark"`, or `"system"` color mode
New in v8+	`brandId`	Render preferences using a specific brand’s styling
New in v8+	`channelLabels`	Rename how delivery channels appear in the UI
New in v8+	`onError`	Callback invoked when the component encounters an error

Set tenantId once on signIn. It scopes both <CourierPreferences> and the headless useCourier().preferences hooks automatically.

6b. Theming

Like Inbox and Toast, v8+ Preferences drops styled-components and themes natively through the lightTheme and darkTheme props. The fields are in .

6c. React hooks

A custom Preferences UI using the v7 usePreferences() hook from @trycourier/react-hooks should move to useCourier().preferences. Courier’s React hooks now ship inside @trycourier/courier-react. Remove any dependency on @trycourier/react-hooks.

App.tsx

import { usePreferences } from "@trycourier/react-hooks"; 
import { useCourier } from "@trycourier/courier-react"; 

const MyCustomPreferences = () => {
  const preferences = usePreferences(); 
  const { preferences } = useCourier(); 

  useEffect(() => {
    preferences.fetchRecipientPreferences(); 
    load(); 
  }, []);

  async function load() { 
    const prefs = await preferences.getUserPreferences(); 
    // prefs.items is the list of preference topics
    setTopics(prefs.items); 
  } 

  return null;
}

Method signature changes

v7 signature	v8+ signature
`preferences.fetchRecipientPreferences(tenantId?)` (result on `preferences.recipientPreferences`)	`preferences.getUserPreferences(props?: { paginationCursor?: string })` returns `Promise<CourierUserPreferences>`
`preferences.updateRecipientPreferences(payload)`	`preferences.putUserPreferenceTopic({ topicId, status, hasCustomRouting, customRouting, digestSchedule? })`
`preferences.fetchPreferencePage(tenantId?, draft?)`	Scope the tenant via `signIn`. Draft-preview isn’t yet available in v8+
New in v8+	`preferences.getUserPreferenceTopic({ topicId })`
New in v8+	`preferences.getDigestSchedules({ topicId })`

config and clientKey info are removed from hooks in v8+. Tenant scoping moves from a per-call tenantId argument to signIn.

has the full signatures and a working example.

SDK documentation

Markdown rendering

Courier React 1.13.0 through 7.x.x render Markdown-formatted messages automatically, such as those produced when Markdown Rendering is enabled for the Courier Inbox provider. v8+ has no built-in Markdown rendering. Add it with custom Inbox components, as below with markdown-to-jsx.

package.json

{
  "dependencies": {
    "@trycourier/courier-react": "^8.0.28",
    "markdown-to-jsx": "^7.7.13", 
    "react": "^19.1.1",
    "react-dom": "^19.1.1"
  }
}

App.tsx

import {
  CourierInbox,
  type CourierInboxListItemFactoryProps
} from '@trycourier/courier-react';
import Markdown from "markdown-to-jsx"; 

export default function App() {
  return (
    <CourierInbox
      renderListItem={(props: CourierInboxListItemFactoryProps) => {
        return (
          <Markdown>{ props.message.preview || "Empty message" }</Markdown>
        );
      }}
    />
  );
}

Troubleshooting

Migrate Inbox and Toast together. The v8+ SDK depends on a newer major version of @trycourier/courier-js than v7 does. Two versions on one page isn’t supported. No requests to Courier after upgrading? Two versions of a @trycourier/ package are probably installed at once. Run npm dedupe, yarn dedupe, or your package manager’s equivalent. Still stuck? Open an issue on GitHub or contact Courier Support.

Get started

Send your first message

Build a notification

Send to many people

Send when something happens

Let users choose

Go live

Move to Courier

Courier React v8 migration guide

What’s new in React v8+

What’s in this guide

Migration steps

1. Upgrade dependencies

2. Generate JWTs

3. Authenticate the Courier SDK

4. Upgrade Inbox components

4a. Theming

Dark mode

4b. Custom components

Custom component prop changes

4c. React hooks

Method signature changes

4d. Feeds and tabs

5. Upgrade Toast components

5a. Toast props

5b. Theming

Dark mode

5c. Custom components

5d. React hooks

Method signature changes

6. Upgrade Preferences components

6a. Preferences props

6b. Theming

6c. React hooks

Method signature changes

SDK documentation

Markdown rendering

Troubleshooting

​What’s new in React v8+

​What’s in this guide

​Migration steps

​1. Upgrade dependencies

​2. Generate JWTs

​3. Authenticate the Courier SDK

​4. Upgrade Inbox components

​4a. Theming

Dark mode

​4b. Custom components

Custom component prop changes

​4c. React hooks

​Method signature changes

​4d. Feeds and tabs

​5. Upgrade Toast components

​5a. Toast props

​5b. Theming

Dark mode

​5c. Custom components

​5d. React hooks

​Method signature changes

​6. Upgrade Preferences components

​6a. Preferences props

​6b. Theming

​6c. React hooks

​Method signature changes

​SDK documentation

​Markdown rendering

​Troubleshooting

What’s new in React v8+

What’s in this guide

Migration steps

1. Upgrade dependencies

2. Generate JWTs

3. Authenticate the Courier SDK

4. Upgrade Inbox components

4a. Theming

4b. Custom components

4c. React hooks

Method signature changes

4d. Feeds and tabs

5. Upgrade Toast components

5a. Toast props

5b. Theming

5c. Custom components

5d. React hooks

Method signature changes

6. Upgrade Preferences components

6a. Preferences props

6b. Theming

6c. React hooks

Method signature changes

SDK documentation

Markdown rendering

Troubleshooting