npm package: @growth-rail/react
Description: Growth Rail React SDK
Latest version: 2.1.1

# @growth-rail/react

The Official Growth Rail React SDK. Easily integrate referral programs, track user growth, and display referral dashboards in your React applications.

## 🚀 Features

-   **Context-based Initialization**: Seamless setup with `GrowthRailProvider`.
-   **Hooks for Ease of Use**: Access the SDK anywhere with the `useGrowthRail` hook.
-   **Built-in UI Components**: Drop-in widgets like `ReferralDashboard` to get started instantly.
-   **Fully Type-Safe**: Written in TypeScript with complete definition support.
-   **Small Footprint**: Optimized for performance and minimal bundle size.

## 📦 Installation

This package requires `@growth-rail/core` as a dependency and `react` as a peer dependency.

```bash
# npm
npm install @growth-rail/react @growth-rail/core

# yarn
yarn add @growth-rail/react @growth-rail/core

# pnpm
pnpm add @growth-rail/react @growth-rail/core
```

## 🛠 Usage

### 1. Wrap your App with `GrowthRailProvider`

Initialize the SDK at the root of your application. Provide your Project Secret Key and optionally a `userId` if the user is already authenticated.

```tsx
import { GrowthRailProvider } from '@growth-rail/react';

function App() {
  return (
    <GrowthRailProvider 
      projectSecretKey="your_project_secret_key_here" 
      userId="user_123" // Optional: initialize for a specific user
      debug={true}      // Enable verbose console logging
    >
      <your-application-code />
    </GrowthRailProvider>
  );
}
```

### 2. Track Events and Get User Info

Use the `useGrowthRail` hook in any child component to track events or initialize users.

```tsx
import { useGrowthRail } from '@growth-rail/react';

export function ActionButton() {
  const { trackRewardEvent, isLoading } = useGrowthRail();

  const handleAction = async () => {
    await trackRewardEvent('purchase_completed');
    console.log('Action tracked!');
  };

  return (
    <button onClick={handleAction} disabled={isLoading}>
      {isLoading ? 'Processing...' : 'Complete Action'}
    </button>
  );
}
```

### 3. Display the Referral Dashboard

Use the `ReferralDashboard` component to provide a white-labeled UI where users can see their referral link and rewards.

```tsx
import { ReferralDashboard } from '@growth-rail/react';

export function DashboardPage() {
  return (
    <div style={{ padding: '20px' }}>
      <h1>My Rewards</h1>
      <ReferralDashboard 
        title="Invite your friends and earn!" 
        onLinkCopied={() => alert('Link copied!')}
      />
    </div>
  );
}
```

## 📖 API Reference

### `useGrowthRail()`

The main hook for interacting with the Growth Rail SDK.

**Methods:**
- `initAppUser(userId)`: Initializes the SDK for a specific user.
- `trackRewardEvent(eventName?)`: Tracks a custom event for attribution and rewards.
- `showReferralDashboard(options?)`: Programmatically triggers the referral dashboard modal.
- `showFloatingButton(options)`: Displays the floating referral trigger button.
- `hideFloatingButton()`: Removes the floating referral trigger button.

**State:**
- `isLoading`: Boolean indicating if an async operation is pending.
- `error`: The last error that occurred (if any).

### `ReferralDashboard`

An inline dashboard component for your application.

| Prop | Type | Description |
| :--- | :--- | :--- |
| `title` | `string` | Optional title for the dashboard. |
| `onLinkCopied` | `() => void` | Callback when the referral link is copied. |

For full documentation, visit [docs.growthrail.com](https://docs.growthrail.com).

## 📄 License

MIT © [Growth Rail](https://growthrail.com)