Skip to main content

​
Overview

Embed Courier’s preference management directly into your application using React components, custom hooks, or web components. This approach provides seamless user experience where notification preferences feel native to your application, with complete control over styling, layout, and user workflow integration. Embedded preferences maintain the full functionality of hosted preference centers while allowing deep customization to match your design system and user experience patterns.
Example Implementation: View the complete Newsletter Preferences example to see embedded preferences in action.

​
Key Features

Embedded preference components provide comprehensive preference management with complete customization control:
  • Seamless Integration - Preferences feel native to your application without external redirects
  • Complete Customization - Full control over styling, layout, and user experience design
  • Multi-Framework Support - React components, custom hooks, and framework-agnostic web components
  • Real-Time Updates - Immediate preference synchronization with Courier’s preference system

​
Core Components

​
React Components

​
PreferencesV4 Component

Pre-built React component that renders a complete preference interface with subscription topics, channel selection, and real-time updates. 
import React from "react";
import { Footer, Header, PreferencesV4 } from "@trycourier/react-preferences";
import { CourierProvider } from "@trycourier/react-provider";

const PreferencePage: React.FunctionComponent<{
  tenantId?: string,
  draft?: boolean,
}> = ({ tenantId, draft = false }) => {
  return (
    <CourierProvider
      clientKey="your_client_key_here"
      userId="current_user_id"
    >
      <Header />
      <PreferencesV4 tenantId={tenantId} draft={draft} />
      <Footer />
    </CourierProvider>
  );
};
Props:
  • tenantId (optional): Specify tenant for multi-tenant applications
  • draft (optional): Show draft preferences before publishing

​
Custom React Hooks

Build completely custom preference interfaces using Courier’s preference hooks for maximum flexibility: 
import React, { useEffect } from 'react';
import { usePreferences } from '@trycourier/react-hooks';

function CustomPreferenceInterface({ tenantId }) {
  const {
    recipientPreferences,
    preferencePage,
    fetchRecipientPreferences,
    fetchPreferencePage,
    updateRecipientPreferences,
    isLoading,
  } = usePreferences();

  useEffect(() => {
    fetchRecipientPreferences(tenantId);
    fetchPreferencePage(tenantId);
  }, [tenantId]);

  const handleToggle = (templateId, currentStatus) => {
    updateRecipientPreferences({
      templateId,
      status: currentStatus === "OPTED_IN" ? "OPTED_OUT" : "OPTED_IN",
      hasCustomRouting: false,
      digestSchedule: "",
      routingPreferences: [],
      tenantId,
    });
  };

  if (isLoading || !preferencePage) {
    return <div>Loading preferences...</div>;
  }

  return (
    <div>
      {recipientPreferences?.map((pref) => (
        <div key={pref.templateId}>
          <label>
            <input
              type="checkbox"
              checked={pref.status === "OPTED_IN"}
              onChange={() => handleToggle(pref.templateId, pref.status)}
            />
            {/* Get friendly name from preferencePage.sections */}
          </label>
        </div>
      ))}
    </div>
  );
}
Hook Returns:
  • recipientPreferences - Array of user preference objects with templateId and status
  • preferencePage - Preference page configuration with sections and topics
  • fetchRecipientPreferences(tenantId) - Function to load user preferences
  • fetchPreferencePage(tenantId) - Function to load preference page structure
  • updateRecipientPreferences(config) - Function to update user preferences
  • isLoading - Boolean indicating if any requests are in progress
The usePreferences hook handles API calls to the User Preferences API internally, providing a React-friendly interface for preference management.
Explore Components: Use this interactive demo to explore Courier’s preference components and their capabilities.

​
Web Components

For non-React applications, use Courier’s web components that work with any JavaScript framework or vanilla HTML: 
<div id="preference-container">
  <courier-preference-page></courier-preference-page>
  
  <script type="text/javascript">
    window.courierConfig = {
      clientKey: 'your_client_key_here',
      userId: 'current_user_id'
    };
  </script>
  <script src="https://courier-components-xvdza5.s3.amazonaws.com/v3.6.4.js"></script>
</div>

​
Implementation Comparison

ApproachBest ForCustomizationDevelopment Effort
PreferencesV4Quick integration, standard UIStyling onlyMinimal
Custom HooksComplex workflows, custom UXComplete controlHigh
Web ComponentsNon-React apps, simple integrationCSS variablesLow

​
Getting Started

​
Installation

yarn add @trycourier/react-hooks @trycourier/react-provider @trycourier/react-preferences styled-components
Package Usage:
  • @trycourier/react-preferences - Pre-built PreferencesV4 component
  • @trycourier/react-hooks - Custom hooks like usePreferences for building custom UIs
  • @trycourier/react-provider - CourierProvider for authentication and context
All @trycourier packages must use the same version for compatibility.

​
Authentication Setup

Get your Client Key from Channels > Courier in your Courier dashboard. Store it securely: 
REACT_APP_COURIER_CLIENT_KEY=your_client_key_here

​
User ID Requirements

Critical: The userId in your preference components must match the to.user_id used in send requests for preference enforcement to work correctly.
Ensure consistent user identification across:
  • Preference component initialization
  • Send API requests
  • User profile management
  • Authentication systems

​
Next Steps

Preferences Editor

Configure subscription topics and sections for your embedded components

Hosted Preference Center

Compare with turnkey hosted preference center solution

User Preferences API

Programmatically manage user preferences and access custom routing data

React SDK Documentation

Explore additional React components and integration patterns