How To Embed Preferences in React

Build a preference center that lives inside your app instead of redirecting users to an external page. The Courier React SDK gives you two approaches: the prebuilt <CourierPreferences> component for quick setup, or the headless useCourier().preferences hooks for a fully custom UI. By the end of this tutorial, your users will be able to toggle notification topics on and off, choose delivery channels (Enterprise), and subscribe to digests directly in your app.

Prerequisites

A Courier account with at least one configured provider
Subscription topics configured in the Preferences Editor (see How To Set Up a Hosted Preference Center Steps 1-2)
A React 17+ application
A backend that generates Courier JWTs for user authentication

If you haven’t created subscription topics and mapped templates yet, complete Steps 1-2 of the hosted preference center tutorial first. The topics and template mappings are the same regardless of how you surface preferences.

Step 1: Install the SDK

The SDK ships as a single package. Install @trycourier/courier-react for React 18+, or @trycourier/courier-react-17 for React 17. They expose the same API.

npm install @trycourier/courier-react

npm install @trycourier/courier-react-17

Step 2: Authenticate with a JWT

Preferences authenticate with a JWT generated by your backend, then signed in on the client with courier.shared.signIn. There is no provider to wrap your app in, and authentication is shared across every Courier component, so if you already signed in for Inbox or Toast you can skip this step. Generate the token server-side with the issue-token API and include the preferences scopes:

{
  "scope": "user_id:{{userId}} read:preferences write:preferences",
  "expires_in": "1d"
}

Fetch that token in your app and call signIn:

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

function useCourierAuth(userId: string) {
  const courier = useCourier();
  const [jwt, setJwt] = useState<string>();

  // Ask your backend for a JWT for this user
  useEffect(() => {
    (async () => {
      const res = await fetch("/api/generate-courier-jwt", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ userId }),
      });
      const { token } = await res.json();
      setJwt(token);
    })();
  }, [userId]);

  // Sign in once the JWT is available
  useEffect(() => {
    if (jwt) courier.shared.signIn({ userId, jwt });
  }, [jwt, userId]);
}

See How to Send a JWT from Your Backend for language-specific backend examples. To scope preferences to a tenant, pass tenantId to signIn: courier.shared.signIn({ userId, jwt, tenantId }).

Critical: The userId you sign in with must match the to.user_id you use when sending, or preference enforcement will not line up.

Option A: Prebuilt Component (Quick Setup)

<CourierPreferences> renders a complete preference interface out of the box: topic toggles, channel selection (Enterprise), and digest scheduling, with the SDK’s modern UI, native theming, and dark mode.

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

function PreferencesPage({ userId }: { userId: string }) {
  const courier = useCourier();
  const [jwt, setJwt] = useState<string>();

  useEffect(() => {
    (async () => {
      const res = await fetch("/api/generate-courier-jwt", {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({ userId }),
      });
      setJwt((await res.json()).token);
    })();
  }, [userId]);

  useEffect(() => {
    if (jwt) courier.shared.signIn({ userId, jwt });
  }, [jwt, userId]);

  return <CourierPreferences />;
}

Props

Prop	Type	Description
`lightTheme` / `darkTheme`	`CourierPreferencesTheme`	Theme for light / dark mode, merged with the defaults
`mode`	`"light" \| "dark" \| "system"`	Color mode (defaults to `"system"`)
`style`	`CSSProperties`	Styles applied to the component container
`title` / `subtitle`	`string`	Override the component’s title and subtitle text
`brandId`	`string`	Render preferences using a specific brand’s styling
`channelLabels`	`Record<string, string>`	Rename how delivery channels appear (e.g. `{ email: "E-mail" }`)
`onError`	`(error: Error) => void`	Called when the component encounters an error

Tenant scope is set on signIn, not per component, so there is no tenantId prop.

Option B: Headless Hooks (Full Control)

For a fully custom UI, read and write preferences through useCourier().preferences.

Fetching Preferences

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

function CustomPreferences() {
  const { preferences } = useCourier();
  const [topics, setTopics] = useState<any[]>([]);

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

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

  if (!topics.length) return <div>Loading preferences...</div>;

  return (
    <div>
      <h2>Notification Preferences</h2>
      {topics.map((topic) => (
        <div key={topic.topicId}>{topic.topicName}</div>
      ))}
    </div>
  );
}

Updating Preferences

Use putUserPreferenceTopic to toggle a topic or set custom routing:

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

function PreferenceToggles() {
  const { preferences } = useCourier();
  const [topics, setTopics] = useState<any[]>([]);

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

  async function load() {
    const prefs = await preferences.getUserPreferences();
    setTopics(prefs.items);
  }

  async function toggle(topic: any) {
    await preferences.putUserPreferenceTopic({
      topicId: topic.topicId,
      status: topic.status === "OPTED_IN" ? "OPTED_OUT" : "OPTED_IN",
      hasCustomRouting: topic.hasCustomRouting,
      customRouting: topic.customRouting,
    });
    load();
  }

  return (
    <div>
      {topics.map((topic) => (
        <label key={topic.topicId} style={{ display: "block", margin: "8px 0" }}>
          <input
            type="checkbox"
            checked={topic.status === "OPTED_IN"}
            onChange={() => toggle(topic)}
          />
          {topic.topicName || topic.topicId}
        </label>
      ))}
    </div>
  );
}

Preference Methods

Method	Description
`getUserPreferences(props?: { paginationCursor?: string })`	Returns `Promise<CourierUserPreferences>`; `.items` holds the topics
`getUserPreferenceTopic({ topicId })`	Fetch a single topic’s preference
`putUserPreferenceTopic({ topicId, status, hasCustomRouting, customRouting, digestSchedule? })`	Update a topic’s status, routing, or digest schedule
`getDigestSchedules({ topicId })`	Read the digest schedules configured for a topic

For the putUserPreferenceTopic payload, status is "OPTED_IN" or "OPTED_OUT", customRouting is an array of channel types (for example ["email", "push"]) applied when hasCustomRouting is true, and digestSchedule sets a digest cadence when the topic supports it.

Step 3: Test Your Implementation

Verify Topic Display

Confirm that all subscription topics from the Preferences Editor appear in your component.

If topics are missing or stale, make sure you’ve clicked Publish in the Preferences Editor. Changes are saved as a draft until you publish.

Test Opt-In/Out

Toggle a topic off, then send a test notification for a template linked to that topic. The notification should be suppressed for the opted-out user.

Verify Channel Selection (Enterprise)

If channel selection is enabled, confirm a user’s channel choices appear when you query the topic from your backend:

curl -X GET https://api.courier.com/users/{user_id}/preferences \
  -H "Authorization: Bearer $COURIER_AUTH_TOKEN"

import Courier from "@trycourier/courier";

const client = new Courier({ apiKey: "your_api_key" });

const { items } = await client.users.preferences.retrieve("user_123");

const topic = items.find((t) => t.topic_id === "TOPIC_ID");
console.log(topic?.custom_routing); // e.g. ["email", "push"]

Theming

Style the prebuilt component with the lightTheme and darkTheme props rather than global CSS. See the Preferences component reference for the theme fields, and use mode to force light, dark, or system. For total control over markup and styles, use the headless hooks in Option B and render your own UI.

What’s Next

Set Up Hosted Preferences

Deploy a hosted preference page as an alternative or complement

Embedding Reference

Full reference for the component and preference hooks

JWT Authentication

Secure your embedded components with JWT tokens

User Preferences API

API reference for server-side preference management

Send Messages

Design Messages

User Journeys

Inbox & Preferences

Deploying and Debugging

Migrate to Courier

How To Embed Preferences in React

Prerequisites

Step 1: Install the SDK

Step 2: Authenticate with a JWT

Option A: Prebuilt Component (Quick Setup)

Props

Option B: Headless Hooks (Full Control)

Fetching Preferences

Updating Preferences

Preference Methods

Step 3: Test Your Implementation

Theming

What’s Next

Set Up Hosted Preferences

Embedding Reference

JWT Authentication

User Preferences API

​Prerequisites

​Step 1: Install the SDK

​Step 2: Authenticate with a JWT

​Option A: Prebuilt Component (Quick Setup)

​Props

​Option B: Headless Hooks (Full Control)

​Fetching Preferences

​Updating Preferences

​Preference Methods

​Step 3: Test Your Implementation

​Theming

​What’s Next

Set Up Hosted Preferences

Embedding Reference

JWT Authentication

User Preferences API

Prerequisites

Step 1: Install the SDK

Step 2: Authenticate with a JWT

Option A: Prebuilt Component (Quick Setup)

Props

Option B: Headless Hooks (Full Control)

Fetching Preferences

Updating Preferences

Preference Methods

Step 3: Test Your Implementation

Theming

What’s Next