f1-telemetry-js

Reusable React + TypeScript component library for Formula 1 telemetry visualization.

Installation

npm install f1-telemetry-js chart.js react-chartjs-2

Quick Usage

import { SpeedChart, fromCsvTelemetry } from "f1-telemetry-js";

const telemetry = fromCsvTelemetry(`time,speed,throttle,brake,x,y
0,122,28,0,12,8
1,150,55,0,18,12
2,188,80,4,24,16
3,215,92,0,30,18`);

export function App() {
  return <SpeedChart time={telemetry.time} speed={telemetry.speed} />;
}

Core Charts

• SpeedChart
• ThrottleBrakeChart
• LapComparisonChart
• TrackMap
• TelemetryDashboard
• GearChart
• EnergyChart
• TyreStrategyTimeline
• GapChart
• PositionChart
• MiniSectors
• SpeedHeatmapTrackMap
• RadarChart
• PitStopTimeline
• WeatherWidget
• TelemetryPlayground
• TelemetryDashboard layout editor (reorder, resize, hide/show, persisted)

Hooks

import { useTelemetry, useCursorSync, SpeedChart, ThrottleBrakeChart } from "f1-telemetry-js";

function Dashboard({ rawData }: { rawData: unknown }) {
  const { telemetry } = useTelemetry({ data: rawData });
  const { cursorProps } = useCursorSync();

  if (!telemetry) return null;

  return (
    <>
      <SpeedChart time={telemetry.time} speed={telemetry.speed} {...cursorProps} />
      <ThrottleBrakeChart
        time={telemetry.time}
        throttle={telemetry.throttle}
        brake={telemetry.brake}
        {...cursorProps}
      />
    </>
  );
}

Available hooks:

• useTelemetry
• useCursorSync
• useAutoTheme
• useChartExport
• TelemetryProvider / useTelemetryContext

Headless Core (f1-telemetry-js/core)

Use the core subpath when you only need parsing, processing, computations, and constants (no React components):

import { fromCsvTelemetry, TEAM_COLORS, computeTimeDelta } from "f1-telemetry-js/core";

For finer-grained imports (smaller bundles in non-React apps):

import { processSeriesDataInWorker } from "f1-telemetry-js/performance";
import { fromOpenF1Telemetry } from "f1-telemetry-js/adapters";
import { SpeedChart } from "f1-telemetry-js/react";
import { registerTelemetryPanel } from "f1-telemetry-js/extensions";

Utility APIs

• formatTelemetry
• validateTelemetry
• processSeriesData
• findNearestIndex
• createLineAnnotationDatasets
• createTrackAnnotationDataset
• normalizeDistance
• computeLapTimes
• computeSectorTimes
• computeSpeedDelta
• interpolateTelemetry
• computeTimeDelta
• detectOvertakes
• classifyTyreCompound
• mergeTelemetry
• exportToJson
• exportToCsv

Reliability features (v1.2)

import {
  fromOpenF1TelemetryWithDiagnostics,
  validateTelemetry
} from "f1-telemetry-js/core";

const adapterResult = fromOpenF1TelemetryWithDiagnostics(rawOpenF1Data, {
  validationMode: "lenient"
});

const strictValidation = validateTelemetry(adapterResult.telemetry, "lap-check", {
  mode: "strict"
});

• Optional extra telemetry channels: gear, ersDeployment, ersHarvest, batteryLevel, airTemp, trackTemp, humidity, windSpeed, rainfall, pressure
• Structured adapter diagnostics for contract monitoring in CI
• Validation modes: strict (errors on mismatches) and lenient (warnings for recoverable shape issues)
• Adaptive downsampling support via downsampleStrategy: "adaptive" and processing.adaptive
• Optional worker processing API: processSeriesDataInWorker(...)
• TelemetryPlayground import wizard for CSV field mapping and transform preview

Plugin Extension API

import { registerTelemetryPanel, telemetryStatsPanel } from "f1-telemetry-js";

registerTelemetryPanel(telemetryStatsPanel);

Built-in extension panels:

• telemetryStatsPanel
• gearDistributionPanel
• lapSummaryPanel
• stintDegradationPanel
• sectorPaceEvolutionPanel
• overtakeTimelinePanel

Panels can also include:

• lifecycle hooks: onMount / onUnmount
• panel context menu actions: contextMenuActions
• shared state channels via context.shared.publish/read/subscribe

v2 Namespace Migration

Recommended import layout in v2:

• React UI + hooks: f1-telemetry-js/react
• Data/processing utilities: f1-telemetry-js/core
• Adapter-only imports: f1-telemetry-js/adapters
• Extension SDK + panels: f1-telemetry-js/extensions

To automate most import updates:

npm run codemod:v2-imports -- ./src

v2 also standardizes telemetry/event time semantics through normalizeTelemetryTime(...) with explicit timeReference.

React Native

f1-telemetry-js components use Chart.js (HTML canvas), which doesn't run in React Native.

For React Native projects, use the headless core for data processing:

import { fromOpenF1Telemetry, TEAM_COLORS, computeTimeDelta } from "f1-telemetry-js/core";

Then render visuals with a React Native charting library (victory-native, react-native-chart-kit, or react-native-skia).

Official wrappers and ecosystem packages:

• @f1-telemetry-js/vue
• @f1-telemetry-js/svelte
• @f1-telemetry-js/react-native-core

Vue.js

Use the headless core for data processing in Vue apps:

import { fromCsvTelemetry, formatTelemetry, TEAM_COLORS } from "f1-telemetry-js/core";

Pair with Vue charting libraries like vue-chartjs or ECharts wrappers.

Svelte / SvelteKit

Use the headless core for data processing:

import { fromFastF1Telemetry, computeLapTimes, TRACKS } from "f1-telemetry-js/core";

Pair with a Svelte charting library such as layercake or pancake.

Development

npm run lint
npm run test:run
npm run build
npm run benchmark:ci
npm run benchmark:update-baseline
npm run api:check
npm run storybook