> ## Documentation Index
> Fetch the complete documentation index at: https://docs.novu.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Subscription

> Use useSubscriptions, useCreateSubscription, and related React hooks to fetch, create, and manage Novu topic subscriptions from your frontend.

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.

<Note>
  If you prefer to use the default Subscription components, refer to the [Subscription components documentation](/platform/subscription/quickstart).
</Note>

## `useSubscriptions`

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

### Hook parameters

| Property | Type | Description |
| - | - | - |
| `topicKey` | `string` | The unique key of the topic to fetch subscriptions for. |
| `onSuccess` | `(data: TopicSubscription[]) => void` | Callback function called when subscriptions are successfully fetched |
| `onError` | `(error: NovuError) => void` | Callback function called when an error occurs |

### Return value

| Property | Type | Description | |
| - | - | - | - |
| `subscriptions` | `TopicSubscription[]` | Array of subscription objects for the topic (default: `[]`) | |
| `error` | \`NovuError | undefined\` | Error object if the request failed |
| `isLoading` | `boolean` | True during the initial load | |
| `isFetching` | `boolean` | True 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.

```tsx theme={null}
import { useSubscriptions } from "@novu/react";

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

## `useSubscription`

Fetches a specific subscription instance.

### Hook parameters

| Property | Type | Description | |
| - | - | - | - |
| `topicKey` | `string` | The unique key of the topic. | |
| `identifier` | `string` | The unique identifier of the specific subscription instance. | |
| `onSuccess` | \`(data: TopicSubscription | null) => void\` | Callback function called when the subscription is fetched |
| `onError` | `(error: NovuError) => void` | Callback function called when an error occurs | |

### Return value

| Property | Type | Description | |
| - | - | - | - |
| `subscription` | \`TopicSubscription | null\` | The specific subscription object |
| `error` | \`NovuError | undefined\` | Error object if the request failed |
| `isLoading` | `boolean` | True 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.

```tsx theme={null}
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

| Property | Type | Description | |
| - | - | - | - |
| `create` | `(args: CreateSubscriptionArgs) => Promise<{ data?: TopicSubscription; error?: NovuError }>` | Function to create a new subscription. | |
| `isCreating` | `boolean` | True while the create request is in progress | |
| `error` | \`NovuError | undefined\` | 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.

```tsx theme={null}
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

| Property | Type | Description | |
| - | - | - | - |
| `update` | `(args: UpdateSubscriptionArgs) => Promise<{ data?: TopicSubscription; error?: NovuError }>` | Function to update an existing subscription. | |
| `isUpdating` | `boolean` | True while the update request is in progress | |
| `error` | \`NovuError | undefined\` | 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.

```tsx theme={null}
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

| Property | Type | Description | |
| - | - | - | - |
| `remove` | `(args: DeleteSubscriptionArgs) => Promise<{ data?: void; error?: NovuError }>` | Function to remove a subscription. | |
| `isRemoving` | `boolean` | True while the delete request is in progress | |
| `error` | \`NovuError | undefined\` | Error object if the last remove request failed |

### Example usage

This example renders an unsubscribe button that removes the subscription when clicked.

```tsx theme={null}
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>
  );
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.