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

# Subscription

> 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.

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