Customize the preference center

covers embedding it. Theme it or build your own UI on the same methods, below.

Theme

Theme the preferences center with lightTheme / darkTheme (a CourierPreferencesTheme). Set mode to "light", "dark", or "system". The default is "system", which follows the user’s OS setting.

import { CourierPreferences } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

const lightTheme = { /* CourierPreferencesTheme */ };
const darkTheme = { /* CourierPreferencesTheme */ };

<CourierPreferences lightTheme={lightTheme} darkTheme={darkTheme} mode="system" />;

<courier-preferences id="preferences"></courier-preferences>

<script type="module">
  import { Courier } from "@trycourier/courier-ui-preferences";

  const preferences = document.getElementById("preferences");
  preferences.setLightTheme({ /* CourierPreferencesTheme */ });
  preferences.setDarkTheme({ /* CourierPreferencesTheme */ });
</script>

<script setup lang="ts">
import { CourierPreferences } from "@trycourier/courier-vue";

const lightTheme = { /* CourierPreferencesTheme */ };
const darkTheme = { /* CourierPreferencesTheme */ };
</script>

<template>
  <CourierPreferences :lightTheme="lightTheme" :darkTheme="darkTheme" mode="system" />
</template>

import { Component } from "@angular/core";
import { CourierPreferencesComponent, CourierPreferencesTheme } from "@trycourier/courier-angular";

@Component({
  selector: "app-preferences",
  standalone: true,
  imports: [CourierPreferencesComponent],
  template: `<courier-preferences [lightTheme]="lightTheme" [darkTheme]="darkTheme" mode="system"></courier-preferences>`,
})
export class PreferencesComponent {
  lightTheme: CourierPreferencesTheme = { /* ... */ };
  darkTheme: CourierPreferencesTheme = { /* ... */ };
}

// UIKit
let preferences = CourierPreferences(
  mode: .channels(CourierUserPreferencesChannel.allCases),
  lightTheme: CourierPreferencesTheme(/* ... */),
  darkTheme: CourierPreferencesTheme(/* ... */)
)

// SwiftUI
CourierPreferencesView(
  mode: .channels(CourierUserPreferencesChannel.allCases),
  lightTheme: CourierPreferencesTheme(/* ... */),
  darkTheme: CourierPreferencesTheme(/* ... */)
)

// `mode` and the themes are properties on the view, not constructor arguments
val preferences = findViewById<CourierPreferences>(R.id.courierPreferences)
preferences.mode = CourierPreferences.Mode.Channels(CourierPreferenceChannel.allCases)
preferences.lightTheme = CourierPreferencesTheme(/* ... */)
preferences.darkTheme = CourierPreferencesTheme(/* ... */)

CourierPreferences(
  mode: ChannelsMode(channels: CourierUserPreferencesChannel.allCases),
  lightTheme: CourierPreferencesTheme(/* ... */),
  darkTheme: CourierPreferencesTheme(/* ... */),
);

<CourierPreferencesView theme={{ light: { /* ... */ }, dark: { /* ... */ } }} />;

On the web the theme is a CourierPreferencesTheme, identical across React, Vue, Angular, and the Web Components, so it is documented once below. The native SDKs have their own: , , , and .

CourierPreferencesTheme reference

Every property is optional. Set primaryColor alone and it carries the accent through the toggles, radios, and chips, which is usually the whole change.

type CourierPreferencesTheme = {
  primaryColor?: string;             // accent, defaults to the inbox blue
  title?: FontTheme;                 // the page heading
  subtitle?: FontTheme;              // the line under it
  container?: { font?: FontTheme };  // inherited by everything inside

  loading?: {
    animation?: {
      barColor?: string;
      barHeight?: string;
      barBorderRadius?: string;
      duration?: string;             // one shimmer cycle, e.g. '2s'
    };
  };

  // error and empty take the same shape
  error?: InfoStateTheme;
  empty?: InfoStateTheme;

  section?: {
    title?: FontTheme;
    description?: FontTheme;
    backgroundColor?: string;
  };

  topic?: {
    backgroundColor?: string;
    border?: string;
    borderRadius?: string;
    title?: FontTheme;
    description?: FontTheme;
    statusLabel?: FontTheme;
    toggle?: {
      trackColor?: string;
      trackActiveColor?: string;
      thumbColor?: string;
      borderRadius?: string;
    };
  };

  digest?: {
    font?: FontTheme;                // unselected schedule options
    selectedFont?: FontTheme;
    iconColor?: string;              // the trailing calendar icon
    radio?: {
      ringColor?: string;            // unselected ring
      checkedColor?: string;         // selected ring and inner dot
      font?: FontTheme;
      selectedFont?: FontTheme;
    };
  };

  channelChip?: {
    font?: FontTheme;
    selectedFont?: FontTheme;
    divider?: string;                // CSS border shorthand, above the chips
    checkbox?: {
      checkedColor?: string;         // border and fill when checked
      font?: FontTheme;
      selectedFont?: FontTheme;
    };
  };
};

type FontTheme = { family?: string; weight?: string; size?: string; color?: string };

type InfoStateTheme = {
  title?: { text?: string; font?: FontTheme };
  button?: {
    text?: string;                   // 'Retry' on the error state by default
    font?: FontTheme;
    backgroundColor?: string;
    hoverBackgroundColor?: string;
    border?: string;
    borderRadius?: string;
  };
};

This isn’t the same shape as the inbox theme. Preferences is a flat set of regions (section, topic, digest, channelChip) with a single primaryColor on top, while the inbox theme is a popup and inbox tree. A theme object written for one isn’t partially valid for the other. It applies nothing. Two fields exist but do nothing today: loading.font, kept for compatibility because the loading state renders as a skeleton, and the deprecated CourierPreferencesStatusTheme.

Custom UI

The preferences component doesn’t take render slots yet. To render preferences in your own UI, read and write topics through the preferences client. The same methods exist on every platform. Web frameworks expose them through useCourier() (React/Vue) or the injected service (Angular). Everywhere else uses Courier.shared.client.preferences:

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

const { preferences } = useCourier();

// Read the user's topics, then write a change (client is set after signIn)
const { items } = await preferences.getUserPreferences();

await preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["inbox", "email"],
});

// Read the user's topics, then write a change (client is set after signIn)
const { items } = await Courier.shared.client?.preferences.getUserPreferences();

await Courier.shared.client?.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["inbox", "email"],
});

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

// `preferences` is plain (no .value)
const { preferences } = useCourier();

const { items } = await preferences.getUserPreferences();

await preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["inbox", "email"],
});

import { inject } from "@angular/core";
import { CourierService } from "@trycourier/courier-angular";

const courier = inject(CourierService);

const { items } = await courier.getUserPreferences();

await courier.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["inbox", "email"],
});

// `client` is available after signIn: Courier.shared.client
let prefs = try await client.preferences.getUserPreferences(paginationCursor: nil)

try await client.preferences.putUserPreferenceTopic(
  topicId: "TOPIC_ID",
  status: .optedIn,
  hasCustomRouting: true,
  customRouting: [.push]
)

// `client` is available after signIn: Courier.shared.client
val prefs = client.preferences.getUserPreferences(paginationCursor = null)

client.preferences.putUserPreferenceTopic(
  topicId = "TOPIC_ID",
  status = CourierPreferenceStatus.OPTED_IN,
  hasCustomRouting = true,
  customRouting = listOf(CourierPreferenceChannel.PUSH)
)

// Await the client, available after signIn
final client = await Courier.shared.client;

final prefs = await client.preferences.getUserPreferences(paginationCursor: null);

await client.preferences.putUserPreferenceTopic(
  topicId: "TOPIC_ID",
  status: CourierUserPreferencesStatus.optedIn,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.push],
);

// Get the client, available after signIn
const client = await Courier.shared.getClient();

const prefs = await client.preferences.getUserPreferences({
  paginationCursor: undefined,
});

await client.preferences.putUserPreferenceTopic({
  topicId: "TOPIC_ID",
  status: CourierUserPreferencesStatus.OptedIn,
  hasCustomRouting: true,
  customRouting: [CourierUserPreferencesChannel.Push],
});

See your platform’s SDK reference for the exact signatures.

Methods behind the component

The component reads and writes through courier.shared.preferences, so a UI you build yourself calls the same client. useCourier() returns the client in React.

Method	Returns
`getUserPreferences({ paginationCursor? })`	`CourierUserPreferences`, the user’s topics and their statuses.
`getUserPreferenceTopic({ topicId })`	`CourierUserPreferencesTopic` for one topic.
`putUserPreferenceTopic({ topicId, status, hasCustomRouting, customRouting, digestSchedule? })`	The updated topic.
`getPreferencePage({ accountId?, brandId?, draft? })`	`CourierPreferencePage`, the published section and topic layout, or the draft.
`getDigestSchedules({ topicId })`	The digest schedule options a topic offers.

putUserPreferenceTopic replaces the topic’s routing rather than merging into it. Send hasCustomRouting and the full customRouting array together, because omitting a channel removes it.

const courier = useCourier();

const prefs = await courier.shared.preferences.getUserPreferences();
await courier.shared.preferences.putUserPreferenceTopic({
  topicId: "order-updates",
  status: "OPTED_IN",
  hasCustomRouting: true,
  customRouting: ["email"],
});

Get started

Quickstarts

Inbox

Toasts

Preferences

Customize the preference center

Theme

CourierPreferencesTheme reference

Custom UI

Methods behind the component

​Theme

​CourierPreferencesTheme reference

​Custom UI

​Methods behind the component

Theme

CourierPreferencesTheme reference

Custom UI

Methods behind the component