React Integration

WriteTrack provides a React hook for easy integration with React applications.

Installation

npm

npm i writetrack

pnpm

pnpm add writetrack

yarn

yarn add writetrack

bun

bun add writetrack

React is an optional peer dependency - non-React users won’t have it in their bundle.

Note

The React hook uses autoStart: true by default. The tracker begins recording as soon as the element is mounted and the ref is attached. Set autoStart: false if you need to control when tracking begins.

Basic Usage

ResponseForm.tsx

import React, { useRef } from 'react';
import { useWriteTrack } from 'writetrack/react';

export function ResponseForm() {
  const textareaRef = useRef<HTMLTextAreaElement>(null);
  const { tracker, isTracking } = useWriteTrack(textareaRef);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();

    if (tracker) {
      const data = tracker.getData();
      console.log('Session data:', data);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <textarea ref={textareaRef} placeholder="Type your response..." />
      {isTracking && <p>Tracking keystrokes...</p>}
      <button type="submit">Submit</button>
    </form>
  );
}

API Reference

useWriteTrack

function useWriteTrack(
  ref: RefObject<HTMLElement | null>,
  options?: UseWriteTrackOptions
): UseWriteTrackReturn;

Parameters

Parameter	Type	Description
ref	RefObject<HTMLElement>	React ref attached to the input element
options.license	string	WriteTrack license key
options.userId	string	User identifier included in metadata
options.contentId	string	Content identifier included in metadata
options.metadata	Record<string, unknown>	Additional metadata
options.autoStart	boolean	Auto-start tracking when element mounts (default: true)
options.wasmUrl	string	URL to WASM binary for analysis
options.persist	boolean	Enable IndexedDB session persistence (requires contentId)

Caution

Options are read once when the element mounts. Changing options after mount (e.g., a new license or contentId) will not recreate the tracker. Call reset() to apply new options.

Return Value

Property	Type	Description
start	() => void	Start tracking (if autoStart was false)
stop	() => void	Stop tracking
reset	() => void	Reset tracker and clear state
isTracking	boolean	Whether tracker is active
tracker	WriteTrack | null	Underlying WriteTrack instance

Tip

Access the underlying tracker instance to call data methods like tracker.getData() and tracker.getRawEvents().

Examples

Manual Start/Stop

ControlledForm.tsx

import React, { useRef } from 'react';
import { useWriteTrack } from 'writetrack/react';

export function ControlledForm() {
  const inputRef = useRef<HTMLInputElement>(null);
  const { start, stop, tracker, isTracking } = useWriteTrack(inputRef, {
    autoStart: false,
  });

  return (
    <div>
      <input ref={inputRef} type="text" />

      <button onClick={isTracking ? stop : start}>
        {isTracking ? 'Stop' : 'Start'} Tracking
      </button>

      <button onClick={() => tracker && console.log(tracker.getData())}>
        Get Data
      </button>
    </div>
  );
}

With Multiple Inputs

function MultiFieldForm() {
  const nameRef = useRef<HTMLInputElement>(null);
  const emailRef = useRef<HTMLInputElement>(null);
  const messageRef = useRef<HTMLTextAreaElement>(null);

  // Track the main content field
  const { tracker } = useWriteTrack(messageRef);

  const handleSubmit = (e: React.FormEvent) => {
    e.preventDefault();
    if (tracker) {
      const data = tracker.getData();
      console.log('Session:', data.quality);
    }
  };

  return (
    <form onSubmit={handleSubmit}>
      <input ref={nameRef} placeholder="Name" />
      <input ref={emailRef} placeholder="Email" />
      <textarea ref={messageRef} placeholder="Message (tracked)" />
      <button type="submit">Send</button>
    </form>
  );
}

TypeScript

import type {
  UseWriteTrackReturn,
  UseWriteTrackOptions,
} from 'writetrack/react';