@signal-js/react

React hooks and components for Signal SDK. Uses @signal-js/browser for the core SDK (included as a dependency).

Installation

npm install @signal-js/react
# or
pnpm add @signal-js/react
# or
yarn add @signal-js/react

Quick Start

Provider Setup

import { SignalProvider } from '@signal-js/react';

function App() {
  return (
    <SignalProvider
      options={{
        endpoint: 'https://your-api.com/events',
        apiKey: 'your-api-key',
        projectId: 'your-project-id',
        enableSessionReplay: true,
      }}
    >
      <YourApp />
    </SignalProvider>
  );
}

Using Hooks

import { useSignal, useSignalCapture, usePageView } from '@signal-js/react';

function MyComponent() {
  const { capture, identify, group, isRecording } = useSignal();
  
  // Track page view on mount
  usePageView('dashboard');
  
  const handleLogin = (user) => {
    // Identify the user
    identify(user.id, {
      email: user.email,
      name: user.name,
    });
    
    // Associate with company
    group('company', user.companyId);
  };
  
  const handleClick = () => {
    capture('button_clicked', { buttonId: 'submit' });
  };
  
  return (
    <div>
      <p>Recording: {isRecording ? 'Yes' : 'No'}</p>
      <button onClick={handleClick}>Submit</button>
    </div>
  );
}

Hooks

useSignal()

Main hook for accessing Signal SDK.

const {
  signal,           // SignalJS instance
  isInitialized,    // Boolean
  isRecording,      // Boolean
  sessionId,        // Current session ID
  distinctId,       // Current user ID
  capture,          // (event, properties?) => void
  identify,         // (distinctId, traits?) => void
  group,            // (groupType, groupKey, properties?) => void
  register,         // (properties) => void
  reset,            // () => void
  startRecording,   // () => Promise<void>
  stopRecording,    // () => void
  pauseRecording,   // () => void
  resumeRecording,  // () => void
  flush,            // () => Promise<void>
} = useSignal();

useSignalCapture()

Returns a memoized capture function.

const capture = useSignalCapture();
capture('event_name', { property: 'value' });

useSignalIdentify()

Hook for user identification.

const { identify, distinctId, reset } = useSignalIdentify();
identify('user-123', { email: '[email protected]' });

useSignalGroup()

Hook for group management.

const { group, getGroups } = useSignalGroup();
group('company', 'acme-corp', { plan: 'enterprise' });

useSignalSession()

Hook for session information.

const { sessionId, windowId, sessionDuration, isRecording } = useSignalSession();

usePageView()

Captures page view on mount.

usePageView('dashboard', { section: 'analytics' });

useTrackEvent()

Returns a typed capture function for a specific event.

const trackPurchase = useTrackEvent<{ amount: number }>('purchase');
trackPurchase({ amount: 99.99 });

HOC

withSignal()

Higher-order component for class components.

import { withSignal, WithSignalProps } from '@signal-js/react';

class MyComponent extends React.Component<Props & WithSignalProps> {
  handleClick = () => {
    this.props.signal?.capture('clicked');
  };
  
  render() {
    return <button onClick={this.handleClick}>Click</button>;
  }
}

export default withSignal(MyComponent);

License

MIT