Embedding Preferences

Overview

Embed Courier’s preference management directly into your application with the Courier React SDK (@trycourier/courier-react). Use the prebuilt <CourierPreferences> component for a themed, drop-in UI, or the headless useCourier().preferences hooks to build a completely custom interface. Either way, preferences feel native to your app and stay in sync with Courier’s preference system in real time.

Install

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

npm install @trycourier/courier-react

Authentication

Preferences authenticate with a JWT, not a client key. Generate the token server-side and include the read:preferences and write:preferences scopes, then sign in once with courier.shared.signIn. Authentication is shared across every Courier component, so if you have already signed in for Inbox or Toast, no additional sign-in is needed.

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

function AuthGate({ userId, jwt }: { userId: string; jwt: string }) {
  const courier = useCourier();

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

  return null;
}

To scope preferences to a tenant, pass tenantId to signIn (courier.shared.signIn({ userId, jwt, tenantId })). It applies to both the component and the headless hooks. See How to generate a JWT for issuing tokens.

Critical: The userId you sign in with must match the to.user_id used in your send requests, or preference enforcement will not line up.

Prebuilt Component

<CourierPreferences> renders a complete preference interface (subscription topics, channel selection, digest schedules) with the SDK’s modern UI, native theming, and built-in dark mode.

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

function PreferencePage({ userId, jwt }: { userId: string; jwt: string }) {
  const courier = useCourier();

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

  return <CourierPreferences />;
}

Props

Prop	Type	Description
`lightTheme` / `darkTheme`	`CourierPreferencesTheme`	Theme for light / dark mode, merged with the defaults (override only what you need). See the Preferences component reference.
`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 in the UI (e.g. `{ email: "E-mail" }`).
`onError`	`(error: Error) => void`	Called when the component encounters an error.

Theming is applied natively through props (no styled-components). Theme utilities defaultPreferencesLightTheme, defaultPreferencesDarkTheme, and mergePreferencesTheme(mode, overrideTheme) are exported for building on the defaults. Tenant scope is set on signIn, not per component.

Headless Hooks

For a fully custom UI, read and write preferences through useCourier().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
  }

  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 (
    <ul>
      {topics.map((topic) => (
        <li key={topic.topicId}>
          <label>
            <input
              type="checkbox"
              checked={topic.status === "OPTED_IN"}
              onChange={() => toggle(topic)}
            />
            {topic.topicName}
          </label>
        </li>
      ))}
    </ul>
  );
}

Preference Methods

Method	Description
`getUserPreferences(props?: { paginationCursor?: string })`	Returns `Promise<CourierUserPreferences>`; `.items` holds the preference 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 schedule options configured for a topic.
`getNotificationCenterUrl({ clientKey })`	Return the hosted preference center URL.

Tenant scope comes from signIn; these methods take no tenantId argument.

Which Approach

Approach	Best for	Customization	Effort
`<CourierPreferences>`	Quick, standard UI	Theming	Minimal
Headless hooks	Custom workflows and UX	Complete control	Higher

For non-React or server-side integrations, use the User Preferences API (REST) directly.

Next Steps

Preferences Editor

Configure subscription topics, sections, and digest schedules

Hosted Preference Center

Compare with the turnkey hosted option

React v8+ Migration Guide

Full component, theming, and hook reference

User Preferences API

Manage preferences programmatically over REST

Platform

Developer Tools

Help

Embedding Preferences

Overview

Install

Authentication

Prebuilt Component

Props

Headless Hooks

Preference Methods

Which Approach

Next Steps

Preferences Editor

Hosted Preference Center

React v8+ Migration Guide

User Preferences API

​Overview

​Install

​Authentication

​Prebuilt Component

​Props

​Headless Hooks

​Preference Methods

​Which Approach

​Next Steps

Preferences Editor

Hosted Preference Center

React v8+ Migration Guide

User Preferences API

Overview

Install

Authentication

Prebuilt Component

Props

Headless Hooks

Preference Methods

Which Approach

Next Steps