Vue Integration

WriteTrack provides a Vue 3 composable for easy integration with Vue applications.

Installation

npm

npm i writetrack

pnpm

pnpm add writetrack

yarn

yarn add writetrack

bun

bun add writetrack

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

Note

The Vue composable uses autoStart: true by default. The tracker begins recording when the component is mounted and the template ref is attached. Set autoStart: false if you need to control when tracking begins.

Basic Usage

ResponseForm.vue

<script setup lang="ts">
import { ref } from 'vue';
import { useWriteTrack } from 'writetrack/vue';

const textareaRef = ref<HTMLTextAreaElement | null>(null);
const { tracker, isTracking } = useWriteTrack(textareaRef);

function handleSubmit() {
  if (tracker.value) {
    const data = tracker.value.getData();
    console.log('Session data:', data);
  }
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <textarea ref="textareaRef" placeholder="Type your response..." />
    <p v-if="isTracking">Tracking keystrokes...</p>
    <button type="submit">Submit</button>
  </form>
</template>

API Reference

useWriteTrack

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

Parameters

Parameter	Type	Description
elementRef	Ref<HTMLElement>	Vue 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)
options.analysis	boolean	Subscribe to real-time analysis events (requires WASM)
options.onTick	(data: { activeTime: number; totalTime: number; tracker: WriteTrack }) => void	Callback fired every ~1s with active session time and tracker instance
options.onReady	(tracker: WriteTrack) => void	Callback fired when tracker is ready

Caution

Options are read once when the component mounts. Changing options after mount 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	Ref<boolean>	Whether tracker is active
tracker	ShallowRef<WriteTrack | null>	Underlying WriteTrack instance
isReady	Ref<boolean>	Whether tracker has initialised
analysis	ShallowRef<SessionAnalysis | null>	Latest analysis result (when analysis: true)
error	ShallowRef<Error | null>	Latest error from WASM or initialisation

Tip

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

Examples

Manual Start/Stop

ControlledForm.vue

<script setup lang="ts">
import { ref } from 'vue';
import { useWriteTrack } from 'writetrack/vue';

const inputRef = ref<HTMLInputElement | null>(null);
const { start, stop, tracker, isTracking } = useWriteTrack(inputRef, {
  autoStart: false,
});

function toggleTracking() {
  if (isTracking.value) {
    stop();
  } else {
    start();
  }
}
</script>

<template>
  <div>
    <input ref="inputRef" type="text" />

    <button @click="toggleTracking">
      {{ isTracking ? 'Stop' : 'Start' }} Tracking
    </button>

    <button @click="() => tracker && console.log(tracker.getData())">
      Get Data
    </button>
  </div>
</template>

With Multiple Inputs

<script setup lang="ts">
import { ref } from 'vue';
import { useWriteTrack } from 'writetrack/vue';

const nameRef = ref<HTMLInputElement | null>(null);
const emailRef = ref<HTMLInputElement | null>(null);
const messageRef = ref<HTMLTextAreaElement | null>(null);

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

function handleSubmit() {
  if (tracker.value) {
    const data = tracker.value.getData();
    console.log('Session:', data.quality);
  }
}
</script>

<template>
  <form @submit.prevent="handleSubmit">
    <input ref="nameRef" placeholder="Name" />
    <input ref="emailRef" placeholder="Email" />
    <textarea ref="messageRef" placeholder="Message (tracked)" />
    <button type="submit">Send</button>
  </form>
</template>

With Real-Time Analysis

<script setup lang="ts">
import { ref } from 'vue';
import { useWriteTrack } from 'writetrack/vue';

const textareaRef = ref<HTMLTextAreaElement | null>(null);
const { analysis, isReady, error } = useWriteTrack(textareaRef, {
  analysis: true,
  onTick: ({ activeTime }) => {
    console.log(`Active: ${Math.floor(activeTime / 1000)}s`);
  },
  onReady: (tracker) => {
    console.log('Tracker ready:', tracker);
  },
});
</script>

<template>
  <div>
    <textarea ref="textareaRef" />
    <p v-if="!isReady">Initialising...</p>
    <p v-if="error">Error: {{ error.message }}</p>
    <p v-if="analysis">Origin: {{ analysis.contentOrigin.indicator.code }}</p>
  </div>
</template>

TypeScript

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