Embedding Preferences

Embed Courier’s preference management directly in your app 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 your own. Either way, changes 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. Both expose the same API.

npm install @trycourier/courier-react

Authentication

Preferences authenticate with a JWT, not a client key. Generate the token server-side with 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’ve already signed in for Inbox or Toast, you don’t need to sign in again.

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 hooks. See How to generate a JWT for issuing tokens.

The userId you sign in with must match the to.user_id in your send requests, or preference enforcement won’t 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). The defaultPreferencesLightTheme, defaultPreferencesDarkTheme, and mergePreferencesTheme(mode, overrideTheme) utilities 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

Not using React? Embed the <courier-preferences> web component in any framework, or manage preferences from your backend with the User Preferences API.

Platform

Developer Tools

Help

Embedding Preferences

Install

Authentication

Prebuilt Component

Props

Headless Hooks

Preference Methods

Which Approach

​Install

​Authentication

​Prebuilt Component

​Props

​Headless Hooks

​Preference Methods

​Which Approach

Install

Authentication

Prebuilt Component

Props

Headless Hooks

Preference Methods

Which Approach