React

All tracking in the React integration runs on the client side. For React SPAs, use @helionlabs/web directly — create a single shared Helion instance and import it across your components.

Installation

Step 1: Install

npm install @helionlabs/web

Step 2: Initialize

Create a shared Helion instance and export it:

src/helion.ts

import { Helion } from '@helionlabs/web';

export const hl = new Helion({
  clientId: 'YOUR_CLIENT_ID',
  trackScreenViews: true,
  trackOutgoingLinks: true,
  trackAttributes: true,
});

Options

Common options

apiUrl - The url of the helion API or your self-hosted instance
clientId - The client id of your application
clientSecret - The client secret of your application (only required for server-side events)
filter - A function that will be called before sending an event. If it returns false, the event will not be sent
disabled - If true, the library will not send any events

Web options

trackScreenViews - If true, the library will automatically track screen views (default: false)
trackOutgoingLinks - If true, the library will automatically track outgoing links (default: false)
trackAttributes - If true, you can trigger events by using html attributes (<button type="button" data-track="your_event" />) (default: false)
sessionReplay - Session replay configuration object (default: disabled). See session replay docs for full options.
- enabled - Enable session replay recording (default: false)
- maskAllInputs - Mask all input field values (default: true)
- maskTextSelector - CSS selector for text elements to mask (default: [data-helion-replay-mask])
- blockSelector - CSS selector for elements to replace with a placeholder (default: [data-helion-replay-block])
- blockClass - Class name that blocks elements from being recorded
- ignoreSelector - CSS selector for elements excluded from interaction tracking
- flushIntervalMs - How often (ms) recorded events are sent to the server (default: 10000)
- maxEventsPerChunk - Maximum events per payload chunk (default: 200)
- maxPayloadBytes - Maximum payload size in bytes (default: 1048576)
- scriptUrl - Custom URL for the replay script (script-tag builds only)

clientId — Your Helion client ID (required)
apiUrl — API endpoint (default: https://api.helionlabs.dev)
trackScreenViews — Automatically track page navigation (default: true)
trackOutgoingLinks — Track clicks on external links (default: true)
trackAttributes — Track elements with data-track attributes (default: true)
trackHashChanges — Track URL hash changes (default: false)
disabled — Disable all tracking (default: false)

Step 3: Usage

Import and use the instance in your components:

import { hl } from '@/helion';

function MyComponent() {
  const handleClick = () => {
    hl.track('button_click', { button: 'signup' });
  };

  return <button onClick={handleClick}>Trigger event</button>;
}

Usage

Tracking Events

Call hl.track() directly, or use data-track attributes on HTML elements for automatic click tracking.

import { hl } from '@/helion';

function MyComponent() {
  useEffect(() => {
    hl.track('my_event', { foo: 'bar' });
  }, []);

  return <div>My Component</div>;
}

Identifying Users

Call hl.identify() after authentication to associate the session with a known user profile.

import { hl } from '@/helion';

function LoginComponent() {
  const handleLogin = (user: User) => {
    hl.identify({
      profileId: user.id, // Required
      firstName: user.firstName,
      lastName: user.lastName,
      email: user.email,
      properties: {
        tier: 'premium',
      },
    });
  };

  return <button onClick={() => handleLogin(user)}>Login</button>;
}

Setting Global Properties

Properties set via setGlobalProperties are attached to every subsequent event.

import { hl } from '@/helion';

function App() {
  useEffect(() => {
    hl.setGlobalProperties({
      app_version: '1.0.2',
      environment: 'production',
    });
  }, []);

  return <div>App</div>;
}

Incrementing Properties

Increment a numeric property on a user profile. Omit value to increment by 1.

import { hl } from '@/helion';

function MyComponent() {
  const handleAction = () => {
    hl.increment({
      profileId: '1',
      property: 'visits',
      value: 1, // optional
    });
  };

  return <button onClick={handleAction}>Increment</button>;
}

Decrementing Properties

Decrement a numeric property on a user profile. Omit value to decrement by 1.

import { hl } from '@/helion';

function MyComponent() {
  const handleAction = () => {
    hl.decrement({
      profileId: '1',
      property: 'visits',
      value: 1, // optional
    });
  };

  return <button onClick={handleAction}>Decrement</button>;
}

Working with Groups

Groups enable account-level analytics. See the Groups guide for the full walkthrough.

import { hl } from '@/helion';

function LoginComponent() {
  const handleLogin = async (user: User) => {
    // 1. Identify the user
    hl.identify({ profileId: user.id, email: user.email });

    // 2. Sync the group entity with current properties
    hl.upsertGroup({
      id: user.organizationId,
      type: 'company',
      name: user.organizationName,
      properties: { plan: user.plan },
    });

    // 3. Link the user to their group — tags all future events
    hl.setGroup(user.organizationId);
  };

  return <button onClick={() => handleLogin(user)}>Login</button>;
}

Clearing User Data

clear() resets the profile, device identity, session, and all group associations. Call it on logout.

import { hl } from '@/helion';

function LogoutComponent() {
  const handleLogout = () => {
    hl.clear();
    // ... logout logic
  };

  return <button onClick={handleLogout}>Logout</button>;
}

Revenue Tracking

Track revenue events directly or accumulate pending revenue and flush in bulk:

import { hl } from '@/helion';

function CheckoutComponent() {
  const handlePurchase = async () => {
    // Track revenue immediately
    await hl.revenue(29.99, { currency: 'USD' });

    // Or accumulate and flush
    hl.pendingRevenue(29.99, { currency: 'USD' });
    hl.pendingRevenue(19.99, { currency: 'USD' });
    await hl.flushRevenue();

    // Clear pending revenue without sending
    hl.clearRevenue();
  };

  return <button onClick={handlePurchase}>Purchase</button>;
}

Optional: Create a Hook

Wrap the shared instance in a hook for a consistent React-idiomatic API:

src/hooks/useHelion.ts

import { hl } from '@/helion';

export function useHelion() {
  return hl;
}

Use it in components:

import { useHelion } from '@/hooks/useHelion';

function MyComponent() {
  const helion = useHelion();

  useEffect(() => {
    helion.track('my_event', { foo: 'bar' });
  }, []);

  return <div>My Component</div>;
}

Common options

Web options

On this page