> ## Documentation Index
> Fetch the complete documentation index at: https://www.courier.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Install the Courier skill before writing code: `npx skills add trycourier/courier-skills`. It carries the verified SDK shapes and the rules you cannot get wrong.
> Authenticate every request with `Authorization: Bearer <API_KEY>`. A workspace has several environments and each has its own keys, which are plain `pk_` strings with no environment prefix. Start with Test.
> Send with `client.send.message` from the Node SDK (`@trycourier/courier` v7 and later, where the client is the default import). Reference a template by its `nt_` id or its alias.
> A send accepts a bare Elemental element list, but storing content on a template requires the top-level elements wrapped in a channel element.
> To translate a template, write one locale at a time with `PUT /notifications/{id}/locales/{localeId}`, which merges into the existing translations. `PUT /notifications/{id}/content` and `PUT /notifications/{id}/elements/{elementId}` overwrite translations along with the content, so send each element's `id` and `locales` back, and first remove every `checksum` and any `locales` key that starts with an underscore.
> Templates and journeys can be built in the Courier app or created through the API. Either way they live in the workspace and are referenced by ID when you send.
> The hosted MCP server is https://mcp.courier.com. For a briefing on what Courier is and when to use it, read https://www.courier.com/llms.txt.
> Prefer the Guides tab for how-do-I questions and the Docs tab for how-does-it-behave questions. The API reference lives under /api-reference.

# Customize the preference center

> Theme the preferences component for light and dark mode, or build your own UI on the client methods that read and write a user's topics and routing.

[Add a preference center](https://www.courier.com/docs/in-app/add-a-preference-center.md) 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.

![The Courier preferences center with a custom purple theme applied to its topic toggles and channel checkboxes](https://mintcdn.com/courier-4f1f25dc/Ia7FGvhsFU_5CtOa/assets/preferences-theme.webp?fit=max\&auto=format\&n=Ia7FGvhsFU_5CtOa\&q=85\&s=dd2922b0b7016216719db53e6cb53b1d)

The Courier preferences center with a custom theme.

```jsx React highlight={3-4,6} theme={null}
import { CourierPreferences } from "@trycourier/courier-react";  // or "@trycourier/courier-react-17"

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

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

```html Web Components highlight={7-8} theme={null}
<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>
```

```vue Vue highlight={4-5,9} theme={null}
<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>
```

```ts Angular highlight={8,11-12} theme={null}
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 = { /* ... */ };
}
```

```swift iOS highlight={4-5,11-12} theme={null}
// UIKit
let preferences = CourierPreferences(
  mode: .channels(CourierUserPreferencesChannel.allCases),
  lightTheme: CourierPreferencesTheme(/* ... */),
  darkTheme: CourierPreferencesTheme(/* ... */)
)

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

```kotlin Android highlight={4-5} theme={null}
// `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(/* ... */)
```

```dart Flutter highlight={3-4} theme={null}
CourierPreferences(
  mode: ChannelsMode(channels: CourierUserPreferencesChannel.allCases),
  lightTheme: CourierPreferencesTheme(/* ... */),
  darkTheme: CourierPreferencesTheme(/* ... */),
);
```

```jsx React Native theme={null}
<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: [iOS](https://www.courier.com/docs/sdk-libraries/ios.md#preferences-theme), [Android](https://www.courier.com/docs/sdk-libraries/android.md#preferences-theme), [Flutter](https://www.courier.com/docs/sdk-libraries/flutter.md#preferences-theme), and [React Native](https://www.courier.com/docs/sdk-libraries/react-native.md#preferences-theme).

### 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.

```ts theme={null}
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`:

```jsx React theme={null}
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"],
});
```

```js Web Components theme={null}
// 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"],
});
```

```ts Vue theme={null}
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"],
});
```

```ts Angular theme={null}
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"],
});
```

```swift iOS theme={null}
// `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]
)
```

```kotlin Android theme={null}
// `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)
)
```

```dart Flutter theme={null}
// 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],
);
```

```typescript React Native theme={null}
// 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.

```tsx theme={null}
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"],
});
```
