Build your own preferences interface (headless)

Using our @knocklabs/react library, you can create custom notification preference interfaces that are backed by Knock's preferences API. The usePreferences hook enables you to fetch and update user preferences with real-time caching, making it easy to build responsive preference centers.

In this guide, we'll walk through creating a custom preferences interface in your application using the usePreferences hook.

To use this example, you'll need an account on Knock and an identified user. You'll also need:

• A public API key for the Knock environment (set as KNOCK_PUBLIC_API_KEY)
• A default preference set configured in your Knock dashboard

First, we'll need to implement the KnockProvider component somewhere in your component tree and authenticate against the Knock API using a user id and API key.

Next, we'll use the usePreferences hook to fetch and manage user preferences. The hook provides preferences data along with functions to update preferences and loading states.

You can specify which preference set to fetch by passing options to the hook. This is useful when you have multiple preference sets for different contexts or user types.

Workflow preferences control whether users receive notifications for specific workflows. Here's how to build an interface for workflow preferences:

Category preferences enable users to control notifications for groups of related workflows. Here's how to build a category preferences interface:

Here's how to combine different preference types into a complete preference center:

If you're using Knock's multi-tenancy features, you can fetch and update preferences for specific tenants:

The hook also provides access to all preference sets for advanced use cases:

The hook provides loading and validation states to help you build better user experiences:

You now have the building blocks to create sophisticated preference interfaces with Knock. Consider:

• Adding search and filtering functionality for large preference sets
• Implementing bulk actions for managing multiple preferences at once
• Creating preset configurations that users can apply
• Adding preference history and audit trails
• Building role-based preference management for team accounts

• Preferences overview
• Preferences API reference
• React SDK reference