Build your preference center

Docs

Platform

Preferences

Learn how to build and embed a custom notification preference center in your application using Knock's preferences API.

Build your own preference center when you need to embed notification settings directly in your product, control the layout and UX, or support per-tenant preferences, object preferences, and non-default preference sets.

If you want a no-code option instead, see the hosted preference center. Not sure which approach fits? See Choosing a preference center.

Authentication

Building a preference center in your application does not require a secret API key in the browser. Initialize the Knock client with your public API key and authenticate the user with a signed user token from your backend. In production environments with enhanced security mode enabled, Knock requires the signed user token on all client-side requests.

See Security and authentication for details on generating and passing user tokens.

Steps

There are four steps to building a preference center with Knock:

Create a default PreferenceSet

A default preference set is the PreferenceSet users default to using when they first sign up for your product. Any users who don't have a preference set will default to using the default preference set. You can create a default preference set in the Knock dashboard under Platform > Preferences.

Creating a default preference set in Knock dashboard

The default preference set is environment-specific for testing purposes. You can copy the default preference set from one environment to another to keep your environments in sync.

Get a user's preferences

Once you have your default PreferenceSet created, use the Knock client to retrieve the authenticated user's preferences for rendering in your application. If no preferences are set, this returns the default preference set you created in the step above.

For per-tenant preferences, pass the tenant id as the preferenceSet parameter on knockClient.user.getPreferences(). See Per-tenant preferences for details.

Render your preference center

Once you have loaded a user's preference, render an interface in your application so they can update their notification preferences. Typically you encapsulate all of the getting and setting of preferences in a single component.

You define the row structure in your code—mapping preference keys to labels, descriptions, and channel type toggles. See Implementation examples below for React walkthroughs.

Set a user's preferences

When a user makes changes to their preferences in your application, use the Knock client to save those changes back to Knock.

By default, the set method will overwrite any existing PreferenceSet with the new preferences provided. You can learn more about how to update a single preference in the frequently asked questions on the preferences overview.

You can also manage preferences server-side with a secret API key for backend operations like migrations and bulk updates. See the preferences API reference for server-side endpoint details.

Use dashboard-managed config (optional)

Instead of hardcoding row labels and structure in your application, fetch the preference center configuration from Knock and use it to drive your custom UI. This returns the same row definitions you configure in the dashboard under Platform > Preferences > Preference center, including titles, labels, row types, and channel type scopes.

Use your public API key and a signed user token—the same credentials as preferences.get() and preferences.set().

Each row in config.rows maps to a key in the user's default PreferenceSet. Row type values include category, workflow, channel, channel_types, and commercial_subscribed.

The response includes enabled, config (with title, body, and rows), branding, and display metadata such as account_name and user_email. Use config.rows to render your UI, then read and write preference values with knockClient.preferences.get() and knockClient.preferences.set().

See the get preference center config API reference for the full response schema.

Implementation examples

These tutorials use the same auth pattern (public API key + signed user token) and the same preferences.get() / preferences.set() APIs documented above. They walk through building a preference center UI in React.

Quickstart: Preference UIs in React

React

Headless preferences with usePreferences

React

JavaScript SDK preference reference

JavaScript

You can also learn more in the Building in-app UI section of our documentation.