Add a preference center

Try it live:

Preferences demo

See the preferences center in action.

Courier Preferences is an embeddable UI where a signed-in user picks the topics they receive and how each is delivered. It uses the same SDKs and signIn as the inbox. If you already have the inbox, preferences is one more component.

The Courier preferences center with its default styling: a topic section with per-topic toggles and an expanded channel picker for email, push, and SMS — The Courier preferences center with its default styling.

The component renders empty unless the user’s JWT has read:preferences write:preferences in its scope string, as covers.

Set up

Install the SDK for your framework:

npm install @trycourier/courier-react
# On React 17? Use @trycourier/courier-react-17 instead (identical API):
# npm install @trycourier/courier-react-17

npm install @trycourier/courier-ui-preferences

npm install @trycourier/courier-vue

npm install @trycourier/courier-angular

# Swift Package Manager: add https://github.com/trycourier/courier-ios
# or CocoaPods:
pod 'Courier_iOS'

# In settings.gradle add the JitPack repo, then the dependency in build.gradle:
# maven { url 'https://jitpack.io' }
# implementation 'com.github.trycourier:courier-android:<version>'

flutter pub add courier_flutter

npm install @trycourier/courier-react-native
# then, for iOS:
cd ios && pod install

On mobile, the SDK also needs native project setup before it renders: , , , and . Then and render the preferences component:

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

export default function Preferences() {
  return <CourierPreferences />;
}

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

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

  Courier.shared.signIn({ userId, jwt });
</script>

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

<template>
  <CourierPreferences />
</template>

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

@Component({
  selector: "app-preferences",
  standalone: true,
  imports: [CourierPreferencesComponent],
  template: `<courier-preferences></courier-preferences>`,
})
export class PreferencesComponent {}

// Use CourierPreferences (UIKit) or CourierPreferencesView (SwiftUI).
// Both take a display mode; see the SDK reference for the options.
import Courier_iOS

// UIKit
view.addSubview(CourierPreferences(mode: .channels(CourierUserPreferencesChannel.allCases)))

// SwiftUI
CourierPreferencesView(mode: .channels(CourierUserPreferencesChannel.allCases))

// Render the CourierPreferences view from com.courier.android.ui.preferences
// XML: <com.courier.android.ui.preferences.CourierPreferences ... />
val preferences = findViewById<CourierPreferences>(R.id.courierPreferences)

import 'package:courier_flutter/ui/preferences/courier_preferences.dart';

// Render the preferences widget (see the SDK reference for mode options)
CourierPreferences(mode: ChannelsMode(channels: CourierUserPreferencesChannel.allCases));

import { CourierPreferencesView } from "@trycourier/courier-react-native";

export default function Preferences() {
  return <CourierPreferencesView />;
}

Full SDK references: , , , , , , , .

Choose a display mode

The mobile components take a mode that sets how much control the user gets:

Topic mode: one on/off toggle per subscription topic. The simplest option, and the usual choice.
Channels mode: per-channel controls within each topic, so a user can keep a topic but receive it by email only.

CourierPreferencesView(mode: .topic)
CourierPreferencesView(mode: .channels([.push, .sms, .email]))

// `mode` is a property on the view, not a constructor argument
preferences.mode = CourierPreferences.Mode.Topic
preferences.mode = CourierPreferences.Mode.Channels(
  listOf(CourierPreferenceChannel.PUSH, CourierPreferenceChannel.SMS, CourierPreferenceChannel.EMAIL)
)

CourierPreferences(mode: TopicMode())
CourierPreferences(mode: ChannelsMode(channels: [
  CourierUserPreferencesChannel.push,
  CourierUserPreferencesChannel.sms,
  CourierUserPreferencesChannel.email,
]))

<CourierPreferencesView mode={{ type: "topic" }} />
<CourierPreferencesView mode={{ type: "channels", channels: ["push", "sms", "email"] }} />

The web components do not take a display mode. They always render topics with their channel controls. Their mode prop is the theme mode: "light", "dark", or "system". See .

You configure topics and sections in the . For how Courier enforces these choices at send time, see .

Props

<CourierPreferences /> in React, Vue, and Angular. The web component takes the same values as kebab-case attributes, and courier-preferences is the element name.

Prop	Type	Description
`lightTheme`	`CourierPreferencesTheme`	Theme applied in light mode.
`darkTheme`	`CourierPreferencesTheme`	Theme applied in dark mode.
`mode`	`CourierComponentThemeMode`	Force light or dark instead of following the system.
`title`	string	Heading above the topic list.
`subtitle`	string	Line under the heading.
`brandId`	string	Render with a specific Brand’s styling.
`channelLabels`	`Record<string, string>`	Rename a channel in the UI, `{ msteams: "Teams" }`.
`previewData`	`CourierPreferencePage`	Render injected data instead of fetching. No sign-in or network needed.
`isLoading`	boolean	Force the loading skeleton, for while your app fetches data it will inject.
`draft`	boolean	Render the unpublished working draft instead of the published page.
`onError`	`(error: Error) => void`	Called when the component fails to load or save.
`style`	`CSSProperties`	Inline styles on the wrapper.

The web component also exposes setLightTheme, setDarkTheme, setMode, setChannelLabels, setPreviewData, and setLoading on the element, for hosts that hold a ref rather than re-rendering with new props.

Verify

Open the preferences screen

Open the screen that renders the preferences component.

Confirm topics persist

Your workspace’s preference topics appear, and toggling one persists after a reload.

Get started

Quickstarts

Inbox

Toasts

Preferences

Web Components

Add a preference center

Preferences demo

Set up

Choose a display mode

Props

Verify

Preferences demo

​Set up

​Choose a display mode

​Props

​Verify

Set up

Choose a display mode

Props

Verify