usePreferences

Learn how to use the usePreferences hook to manage notification preferences in your React application

The usePreferences hook provides a way to fetch and manage notification preferences for the current subscriber. This includes both global preferences and workflow-specific preferences.

Return Value

type PreferencesReturn = {
  preferences: Array<{
    template: {
      _id: string;
      name: string;
      critical: boolean;
    };
    channels: {
      email?: boolean;
      sms?: boolean;
      in_app?: boolean;
      chat?: boolean;
      push?: boolean;
    };
  }>;
  isLoading: boolean;
  error: Error | null;
  updatePreference: (params: {
    templateId: string;
    channelType: string;
    enabled: boolean;
  }) => Promise<void>;
};

Example Usage

Here's how to use the usePreferences hook to display and manage notification preferences:

import { usePreferences } from '@novu/react';
 
function PreferencesList() {
  const { preferences, isLoading, error, updatePreference } = usePreferences();
 
  if (isLoading) return <div>Loading...</div>;
  if (error) return <div>Error: {error.message}</div>;
 
  return (
    <div>
      {preferences.map((preference) => (
        <div key={preference.template._id}>
          <h3>{preference.template.name}</h3>
 
          <label>
            <input
              type="checkbox"
              checked={preference.channels.email}
              onChange={(e) => {
                updatePreference({
                  templateId: preference.template._id,
                  channelType: 'email',
                  enabled: e.target.checked,
                });
              }}
            />
            Email Notifications
          </label>
 
          <label>
            <input
              type="checkbox"
              checked={preference.channels.sms}
              onChange={(e) => {
                updatePreference({
                  templateId: preference.template._id,
                  channelType: 'sms',
                  enabled: e.target.checked,
                });
              }}
            />
            SMS Notifications
          </label>
        </div>
      ))}
    </div>
  );
}

With Channel Groups

You can organize preferences by channel type:

function ChannelPreferences() {
  const { preferences, updatePreference } = usePreferences();
 
  const emailPreferences = preferences.filter((pref) => pref.channels.email !== undefined);
 
  return (
    <div>
      <h2>Email Preferences</h2>
      {emailPreferences.map((preference) => (
        <div key={preference.template._id}>
          <label>
            <input
              type="checkbox"
              checked={preference.channels.email}
              onChange={(e) => {
                updatePreference({
                  templateId: preference.template._id,
                  channelType: 'email',
                  enabled: e.target.checked,
                });
              }}
            />
            {preference.template.name}
          </label>
        </div>
      ))}
    </div>
  );
}

With Critical Workflows

Some workflows might be marked as critical, meaning they cannot be disabled:

function CriticalPreferences() {
  const { preferences } = usePreferences();
 
  return (
    <div>
      {preferences.map((preference) => (
        <div key={preference.template._id}>
          <h3>{preference.template.name}</h3>
          {preference.template.critical ? (
            <span>Critical - Cannot be disabled</span>
          ) : (
            <label>
              <input
                type="checkbox"
                checked={preference.channels.email}
                onChange={(e) => {
                  updatePreference({
                    templateId: preference.template._id,
                    channelType: 'email',
                    enabled: e.target.checked,
                  });
                }}
              />
              Enable Notifications
            </label>
          )}
        </div>
      ))}
    </div>
  );
}

Changes to preferences are automatically synchronized with the server and will affect future notifications immediately.

Return Value

Example Usage

With Channel Groups

With Critical Workflows

On this page