Introduction

PitchKit is a React-first football pitch visualisation library for the web — mplsoccer's surface, built for the browser. @pitchkit/core is a framework-agnostic engine (coordinate transforms, geometry and the scene model); @pitchkit/react is the officially supported renderer, a set of declarative bindings on top of it, in three families: components (the pitch itself), overlays (data plotted onto it) and charts (football data with no pitch under it).

Install

npm install @pitchkit/core @pitchkit/react

The smallest thing that works

"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).

For the same thing built up step by step against a real match — loading the Euro 2024 final, finding the move that produced England's goal, and plotting it — start with the Quickstart.

Finding your way around

• Quickstart — the guided build: a real match in, a real passage of play out, in four steps.
• Guides — the concepts: coordinates & pitch types, layers, responsive behaviour, and Next.js/SSR.
• Components — the roots that own a coordinate system: <Pitch> and <VerticalPitch>, and <GoalView>, the goal mouth from in front for where shots crossed the line.
• Overlays — layers stacked inside a <Pitch>, one page per visual, each with a live example: Scatter, Arrows, Comet, Annotate, Heatmap, Positional Heatmap, Hexbin, KDE, Polygon, Convex Hull, Voronoi, Goal Angle, Flow, and Player Avatar, the lineup graphic of a match centre.
• Charts — charts with no pitch under them, each a root in its own right: RaceChart, the cumulative step chart usually called an xG race chart or xG timeline, MomentumChart, match momentum as bars with goals and cards on a row of icons beneath, RadarChart, the player radar, and PizzaChart, the percentile pizza.
• Agents — building with AI: llms.txt, and the Agent Skill that ships inside @pitchkit/react.
• Styling — theming with CSS variables, Tailwind utilities, and pitch palettes.
• Data — loading real open football data in one call with the optional @pitchkit/data-providers package: StatsBomb events and 360 tracking, SkillCorner tracking, Wyscout events, Metrica tracking and events, and Impect events — every provider page with a live example fetching a real match.
• mplsoccer → PitchKit — the migration cheatsheet.
• API Reference — every public export, generated from TSDoc.
• Gallery — finished visualisations with full source and sandbox exports.

Reading these docs with an AI agent

Models don't reliably know PitchKit's API, so anything an agent "remembers" about it may be invented. Three ways to give it the real thing, cheapest first:

• /llms.txt — an index of every page on this site, in the llms.txt format. Paste the URL into a prompt.
• /llms-full.txt — every guide, component and overlay page as one Markdown document, examples inlined. Small enough to hand over whole. The generated API reference is kept separate as /llms-api.txt so it doesn't crowd out the prose.
• The Agent Skill — the best option if you're already installing the package, because it's versioned with the code rather than scraped from here.

Any page on this site is also available as raw Markdown: append .md to its URL (for example /docs/styling/theming.md).