npm package: @logsnag/react
Description: LogSnag client for React applications
Author: Shayan
Latest version: 1.0.2

<div align="center">
	<img src="https://logsnag.com/og-image.png" alt="LogSnag"/>
	<br>
    <h1>@logsnag/react</h1>
	<p>Clear, Simple, Effective Product Analytics for SaaS.</p>
	<a href="https://www.npmjs.com/package/@logsnag/react"><img src="https://img.shields.io/npm/v/@logsnag/react" alt="NPM Version"></a>
	<a href="https://discord.gg/dY3pRxgWua"><img src="https://img.shields.io/discord/922560704454750245?color=%237289DA&label=Discord" alt="Discord"></a>
	<a href="https://docs.logsnag.com"><img src="https://img.shields.io/badge/Docs-LogSnag" alt="Documentation"></a>
	<br>
	<br>
</div>

## Installation

### Using npm

```bash
npm install @logsnag/react
```

### Using yarn

```bash
yarn add @logsnag/react
```

### Using pnpm

```bash
pnpm add @logsnag/react
```


## Usage

First, wrap your application with the `LogSnagProvider` at the top level, passing in your project and token:

> Set your token's scope to `public` in the LogSnag dashboard.

```tsx
import { LogSnagProvider } from '@logsnag/react';

function App() {
  return (
    <LogSnagProvider
      token="<TOKEN>"
      project="<PROJECT_NAME>"
    >
      {/* Rest of your app */}
    </LogSnagProvider>
  );
}
```

## Hooks

The `useLogSnag` hook can be used across your React components and provides the following methods:

- `track(options: TrackOptions)`: Track custom events.
- `identify(options: IdentifyOptions)`: Identify user traits.
- `setUserId(userId: string | null)`: Set the user id for the current user. If the user is not logged in, pass null.
- `clearUserId()`: Clear the user id for the current user.
- `setDebug(flag: boolean = true)`: Set debug mode for logging.

```tsx
import { useLogSnag } from '@logsnag/react';

export function Component() {
  // Get the hooks
  const { setUserId, track, identify } = useLogSnag();

  // Set the user id when a user logs in
  setUserId('user-123');

  // Track an event
  track({
    channel: "payments",
    event: "New Subscription",
    user_id: "user-123", // optional when set using setUserId
    icon: "💰",
    notify: true,
    tags: {
      plan: "premium",
      cycle: "monthly",
      trial: false
    }
  });

  // Identify user traits (e.g., name, email, plan, etc.)
  identify({
    user_id: "user-123", // optional when set using setUserId
    properties: {
      name: "John Doe",
      email: "john@doe.com",
      plan: "premium",
    }
  });

  // Rest of your component
}
```

## Tracking Events

You can also track events directly from HTML elements using data attributes:

```jsx
<button
    data-event="Upgraded Plan"
    data-user-id="user-123"     // optional (optional when set using setUserId)
    data-channel="billing"      // optional (defaults to "events")
    data-icon=":moneybag:"      // optional
    data-tag-plan="Pro"         // optional
    data-tag-period="Monthly"   // optional
    data-tag-price="9.99"       // optional
>
    Upgrade to Pro
</button>
```

In this example, when the button is clicked, an event named "Upgraded Plan" will be tracked with the specified tags.

## API Documentation

For more information about the LogSnag API, see: [docs.logsnag.com](https://docs.logsnag.com)

## Support

If you encounter any problems or issues, please contact us at [shayan@logsnag.com](mailto:shayan@logsnag.com)