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

# React SDK

> Microapp subscriptions for React apps.

The Payments SDK for React enables you to subscribe users using React-specific features.

## Getting Started

### 1. Install the SDK

Install the SDK with your preferred package manager.

<CodeGroup>
  ```bash npm theme={null}
  npm install @microapp-io/react
  ```

  ```bash yarn theme={null}
  yarn add @microapp-io/react
  ```

  ```bash pnpm theme={null}
  pnpm add @microapp-io/react
  ```
</CodeGroup>

### 2. Wrap Your App with the Provider

In order for your microapp to have access to payments features, it needs to be wrapped in the `SubscriptionProvider` component:

```tsx theme={null}
import { SubscriptionProvider } from "@microapp-io/react";

function App() {
  return <SubscriptionProvider>{/* Your microapp code here */}</SubscriptionProvider>;
}
```

For local development, we recommend using the `sandbox` feature on the `SubscriptionProvider` component to return mocked subscriptions:

```tsx theme={null}
import { SubscriptionProvider, MicroappSubscriptionPlanCycle } from "@microapp-io/react";

const sandbox = {
  enabled: process.env.NODE_ENV !== "production",
  subscription: () => ({
    id: 'some-subscription-id',
    appId: 'some-app-id',
    user: {
      id: 'some-user-id',
      email: 'email@example.com',
      name: 'FirstName LastName',
    },
    active: true,
    subscriptionPlan: {
      id: 'some-subscription-plan-id',
      name: 'free',
      priceInCents: 0,
      cycle: MicroappSubscriptionPlanCycle.ONE_TIME,
      features: [
        {
          name: 'some-feature-name',
          description: 'some-feature-description'
        },
      ],
      createdAt: new Date(),
      updatedAt: new Date(),
    },
    createdAt: new Date(),
    updatedAt: new Date(),
  }),
};

function App() {
  return (
    <SubscriptionProvider sandbox={sandbox}>
      {/* Your microapp code here */}
    </SubscriptionProvider>
  );
}
```

<Warning>
  The `sandbox` prop should only be used for local development. Do not use it in
  production.
</Warning>

### 3. Use the `useSubscription` Hook

The `useSubscription` hook returns all of the payments data and methods available to your microapp. It returns the following type:

```typescript theme={null}
type Payments = {
  hasSubscribed: boolean;
  isLoading: boolean;
  subscription?: {
    id: string;
    appId: string;
    user: {
      id: string;
      name: string;
    };
    active: boolean;
    subscriptionPlan: {
      id: string;
      name: string;
      description?: string;
      priceInCents: number;
      cycle: MicroappSubscriptionPlanCycle;
      features: Array<{
        id: string;
        name: string;
        description?: string;
      }>;
      createdAt: Date;
      updatedAt: Date;
      archivedAt?: Date;
    };
    paymentsProvider?: string;
    paymentsSubscriptionManagementUrl?: string;
    paymentsSubscriptionId?: string;
    paymentsPaymentId?: string;
    createdAt: Date;
    updatedAt: Date;
    cancelledAt?: Date;
    endsAt?: Date;
  };
  error?: Error;
  requireSubscription: () => void;
};
```

### 4. Prompt the User to Subscribe

You can prompt the user to subscribe by calling the `requireSubscription` method.

```tsx theme={null}
import { useSubscription } from '@microapp-io/react';

function Home() {
  const { requireSubscription } = useSubscription();

  return (
    <button onClick={() => requireSubscription()}>Subscribe</button>
  );
}
```

### 5. Get Notified when the User subscribes

You can get notified when the user subscribes or changes the subscription passing a callback on Payments initialization

```tsx theme={null}
  import { useSubscription } from '@microapp-io/react';

  function Home() {
    const { requireSubscription } = useSubscription({
      onChange: (userSubscription) => console.log('User subscribed', userSubscription),
    });

    requireSubscription();
  }
```

### 6. Example Usage

Here is an example of how you can use the `useSubscription` hook in your microapp:

```tsx theme={null}
import { useSubscription } from "@microapp-io/react";

function Home() {
  const {
    hasSubscribed,
    isLoading,
    subscription,
    error,
    requireSubscription,
  } = useSubscription({
    onChange: (userSubscription) => console.log('User subscribed', userSubscription),
  });

  if (isLoading) {
    return <p>Loading...</p>;
  }

  if (error) {
    return <p>Error: {error.message}</p>;
  }

  if (!hasSubscribed) {
    return <button onClick={() => requireSubscription()}>Subscribe</button>;
  }
}
```