Introduction

PitchKit is a TypeScript-native football pitch visualisation library for the web — mplsoccer's surface, built for the browser. @pitchkit/core is a framework-agnostic engine (coordinate transforms, SVG + Canvas rendering); @pitchkit/react is the officially supported set of declarative bindings on top of it, split into two families: components (the pitch itself) and overlays (data plotted onto it).

Install

npm install @pitchkit/core @pitchkit/react

Quickstart

"use client";

import { Pitch, Scatter } from "@pitchkit/react";

const shots = [
  { x: 108, y: 38, xg: 0.62 },
  { x: 96, y: 48, xg: 0.15 },
];

export function ShotMap() {
  return (
    <Pitch type="statsbomb">
      <Scatter data={shots} x={(s) => s.x} y={(s) => s.y} r={(s) => 3 + s.xg * 9} />
    </Pitch>
  );
}

That's a responsive, server-renderable shot map. Every layer takes plain data plus accessor functions for its visual properties — x, y, and most other props accept either a static value or a per-datum function, which is how PitchKit stays shape-agnostic across providers (StatsBomb, Opta, UEFA, or your own).

Finding your way around

• Guides — the concepts: coordinates & pitch types, layers, theming, responsive behaviour, Next.js/SSR, and recipes.
• Components — the pitch container that owns the coordinate system: <Pitch> and <VerticalPitch>.
• Overlays — layers stacked inside a <Pitch>, one page per visual, each with a live example: Scatter, Arrows, Comet, Annotate, Heatmap, Flow, Polygon, Convex Hull, Voronoi, and Goal Angle.
• Configuration — Tailwind integration.
• mplsoccer → PitchKit — the migration cheatsheet.
• API Reference — every public export, generated from TSDoc.
• Gallery — finished visualisations with full source and sandbox exports.