Subscription | Novu Documentation

Learn how to use the useSubscriptions, useCreateSubscription, and other hooks to manage subscriptions in Novu.

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

Prop	Type	Default
`onError?`	`(error: NovuError) => void`	-
`onSuccess?`	`(data: TopicSubscription[]) => void`	-
`topicKey`	`string`	-

Return value

Prop	Type	Default
`refetch?`	`() => Promise<void>`	-
`isFetching?`	`boolean`	-
`isLoading?`	`boolean`	-
`error?`	`NovuError \| undefined`	-
`subscriptions?`	`TopicSubscription[]`	`[]`

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

Prop	Type	Default
`onError?`	`(error: NovuError) => void`	-
`onSuccess?`	`(data: TopicSubscription \| null) => void`	-
`identifier?`	`string`	-
`topicKey`	`string`	-

Return value

Prop	Type	Default
`refetch?`	`() => Promise<void>`	-
`isLoading?`	`boolean`	-
`error?`	`NovuError \| undefined`	-
`subscription?`	`TopicSubscription \| null`	-

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

Prop	Type	Default
`error?`	`NovuError \| undefined`	-
`isCreating?`	`boolean`	-
`create?`	`(args: CreateSubscriptionArgs) => Promise<{ data?: TopicSubscription; error?: NovuError }>`	-

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

Prop	Type	Default
`error?`	`NovuError \| undefined`	-
`isUpdating?`	`boolean`	-
`update?`	`(args: UpdateSubscriptionArgs) => Promise<{ data?: TopicSubscription; error?: NovuError }>`	-

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

Prop	Type	Default
`error?`	`NovuError \| undefined`	-
`isRemoving?`	`boolean`	-
`remove?`	`(args: { subscriptionId: string; topicKey: string }) => Promise<{ error?: NovuError }>`	-

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>
  );
}

React hooks for subscription management

`useSubscriptions`

Hook parameters

Return value

Example usage

`useSubscription`

Hook parameters

Return value

Example usage

`useCreateSubscription`

Return value

Example usage

`useUpdateSubscription`

Return value

Example usage

`useRemoveSubscription`

Return value

Example usage

On this page