Skip to main content
The @novu/react package provides a set of Subscription hooks for managing topic subscriptions without using the prebuilt Subscription components. These hooks let you build fully custom experiences by working directly with the subscription data model.
If you prefer to use the default Subscription components, refer to the Subscription components documentation.

​
useSubscriptions

Fetches all subscriptions associated with a specific topic for the current subscriber.

​
Hook parameters

PropertyTypeDescription
topicKeystringThe unique key of the topic to fetch subscriptions for.
onSuccess(data: TopicSubscription[]) => voidCallback function called when subscriptions are successfully fetched
onError(error: NovuError) => voidCallback function called when an error occurs

​
Return value

PropertyTypeDescription
subscriptionsTopicSubscription[]Array of subscription objects for the topic (default: [])
error`NovuErrorundefined`Error object if the request failed
isLoadingbooleanTrue during the initial load
isFetchingbooleanTrue while any request is in flight (initial load or refetch)
refetch() => Promise<void>Function to manually trigger a refetch of the list

​
Example usage

This example fetches all subscriptions for a given topic and exposes them for rendering once loading completes. 
import { useSubscriptions } from "@novu/react";

const { subscriptions, isLoading } = useSubscriptions({
  topicKey: "project-123",
});

​
useSubscription

Fetches a specific subscription instance.

​
Hook parameters

PropertyTypeDescription
topicKeystringThe unique key of the topic.
identifierstringThe unique identifier of the specific subscription instance.
onSuccess`(data: TopicSubscriptionnull) => void`Callback function called when the subscription is fetched
onError(error: NovuError) => voidCallback function called when an error occurs

​
Return value

PropertyTypeDescription
subscription`TopicSubscriptionnull`The specific subscription object
error`NovuErrorundefined`Error object if the request failed
isLoadingbooleanTrue during the initial load
refetch() => Promise<void>Function to manually trigger a refetch

​
Example usage

This example shows how to retrieve a specific subscription by its identifier to access its preferences. 
import { useSubscription } from "@novu/react";

const { subscription, isLoading } = useSubscription({
  topicKey: "project-123",
  identifier: "user-preference-1",
});

​
useCreateSubscription

Creates a new subscription to a topic for the current subscriber.

​
Return value

PropertyTypeDescription
create(args: CreateSubscriptionArgs) => Promise<{ data?: TopicSubscription; error?: NovuError }>Function to create a new subscription.
isCreatingbooleanTrue while the create request is in progress
error`NovuErrorundefined`Error object if the last create request failed

​
Example usage

This example demonstrates how to trigger the creation of a new subscription for a topic. 
import { useCreateSubscription } from "@novu/react";

const { create, isCreating } = useCreateSubscription();

await create({
  topicKey: "project-123",
  identifier: "project-updates",
});

​
useUpdateSubscription

Updates an existing subscription’s properties or preferences list.

​
Return value

PropertyTypeDescription
update(args: UpdateSubscriptionArgs) => Promise<{ data?: TopicSubscription; error?: NovuError }>Function to update an existing subscription.
isUpdatingbooleanTrue while the update request is in progress
error`NovuErrorundefined`Error object if the last update request failed

​
Example usage

This example shows how to update the preferences of an existing subscription, such as toggling a specific workflow. 
import { useUpdateSubscription } from "@novu/react";

const { update, isUpdating } = useUpdateSubscription();

const handleToggle = async () => {
  await update({
    topicKey: "project-123",
    subscriptionId: "sub-id-123",
    preferences: [{ workflowId: "workflow-one", enabled: false }]
  });
};

​
useRemoveSubscription

Unsubscribes the current user from a topic by removing the subscription instance.

​
Return value

PropertyTypeDescription
remove(args: DeleteSubscriptionArgs) => Promise<{ data?: void; error?: NovuError }>Function to remove a subscription.
isRemovingbooleanTrue while the delete request is in progress
error`NovuErrorundefined`Error object if the last remove request failed

​
Example usage

This example renders an unsubscribe button that removes the subscription when clicked. 
import { useRemoveSubscription } from "@novu/react";

function UnsubscribeButton({ subscriptionId }) {
  const { remove, isRemoving } = useRemoveSubscription();

  return (
    <button
      onClick={() =>
        remove({
          subscriptionId,
          topicKey: "project-123",
        })
      }
      disabled={isRemoving}
    >
      {isRemoving ? "Removing..." : "Unsubscribe"}
    </button>
  );
}