# PitchKit

> A React and TypeScript football (soccer) visualisation library for the web — mplsoccer's feature set, built for React and Next.js instead of matplotlib. Declarative `<Pitch>` + layer components for shot maps, pass networks, heatmaps, hexbins, KDE surfaces and Voronoi control zones; provider-native coordinates (StatsBomb, SkillCorner, Wyscout, Opta, UEFA), responsive by default, themed with CSS variables, MIT licensed.

PitchKit ships three packages: `@pitchkit/core` (zero-dependency coordinate transforms, geometry and Canvas painters), `@pitchkit/react` (the only supported rendering surface) and `@pitchkit/data-providers` (typed loaders for StatsBomb open data, SkillCorner tracking, and Wyscout events). Composite recipes and theme presets are copied into your project rather than imported.

Every page below is also available as raw Markdown by appending `.md` to its URL.

## Docs

- [Introduction](https://www.pitchkitjs.com/docs): What PitchKit is, and how the pieces fit together.
- [Quickstart](https://www.pitchkitjs.com/docs/quickstart): Build a real chart from real data — the move that produced England's goal in the Euro 2024 final.
- Guides
  - [Coordinates & pitch types](https://www.pitchkitjs.com/docs/guides/coordinates): Provider coordinate systems, the transform pipeline, and how to move data between them.
  - [Layers](https://www.pitchkitjs.com/docs/guides/layers): The mental model — a pitch container, overlay children, and typed accessors.
  - [Responsive](https://www.pitchkitjs.com/docs/guides/responsive): Pitches fill their container by default; fixed pixels are the opt-out.
  - [Next.js & SSR](https://www.pitchkitjs.com/docs/guides/nextjs-ssr): Server-rendered pitches under the App Router, and the one boundary rule to know.
- Components
  - [Pitch](https://www.pitchkitjs.com/docs/components/pitch): The root component — owns the coordinate system and is responsive by default.
- Overlays
  - [Scatter](https://www.pitchkitjs.com/docs/overlays/scatter): Plot discrete points on a pitch, with per-point styling and hover tooltips.
  - [Arrows](https://www.pitchkitjs.com/docs/overlays/arrows): Draw a directional pass or carry map between two points.
  - [Comet](https://www.pitchkitjs.com/docs/overlays/comet): A tapered, optionally fading trail — good for carries and off-ball runs.
  - [Annotate](https://www.pitchkitjs.com/docs/overlays/annotate): Place text labels at pitch coordinates.
  - [Heatmap](https://www.pitchkitjs.com/docs/overlays/heatmap): Canvas-based binned density, for shot maps and touch maps.
  - [Positional Heatmap](https://www.pitchkitjs.com/docs/overlays/positional-heatmap): Density binned into Juego de Posición zones instead of a uniform grid.
  - [Hexbin](https://www.pitchkitjs.com/docs/overlays/hexbin): Hexagonal density binning, for dense touch and event maps.
  - [KDE](https://www.pitchkitjs.com/docs/overlays/kde): A smooth kernel density surface, for pressure and territory maps.
  - [Polygon](https://www.pitchkitjs.com/docs/overlays/polygon): An arbitrary closed shape from a list of points — good for highlighting zones.
  - [Convex Hull](https://www.pitchkitjs.com/docs/overlays/convex-hull): The convex hull of a point set, rendered as a filled polygon — good for touch maps.
  - [Voronoi](https://www.pitchkitjs.com/docs/overlays/voronoi): Voronoi tessellation over a point set, clipped to the pitch — good for coverage/space.
  - [Goal Angle](https://www.pitchkitjs.com/docs/overlays/goal-angle): The angle subtended by the goal mouth at each point, rendered as a wedge.
  - [Flow](https://www.pitchkitjs.com/docs/overlays/flow): Pass/movement data binned by direction and volume, drawn as sized/colored arrows.
- Agents
  - [Overview](https://www.pitchkitjs.com/docs/agents): Build PitchKit charts with a coding agent — prompts to paste, a skill to install, and docs written for models.
  - [Skills](https://www.pitchkitjs.com/docs/agents/skills): The Agent Skill that ships inside @pitchkit/react — versioned with the package, not scraped from this site.
  - [llms.txt](https://www.pitchkitjs.com/docs/agents/llms-txt): This whole site as Markdown, at a URL — for agents that can't read your node_modules.
- Styling
  - [Theming](https://www.pitchkitjs.com/docs/styling/theming): CSS variables only — set once, dark mode for free, override per chart.
  - [Tailwind](https://www.pitchkitjs.com/docs/styling/tailwind): Setting PitchKit's CSS variables and styling marks with Tailwind utilities.
  - [Pitch Palettes](https://www.pitchkitjs.com/docs/styling/palettes): Colour a pitch and its marks with Tailwind classes, using your own palette.
- Data
  - [Overview](https://www.pitchkitjs.com/docs/data): Load real open football data in one call — and when not to bother.
  - StatsBomb
    - [Events](https://www.pitchkitjs.com/docs/data/statsbomb/events): Competitions, matches and events from StatsBomb open data — typed, filtered, plotted.
    - [360 Tracking](https://www.pitchkitjs.com/docs/data/statsbomb/360): Every visible player's position at the moment of an event — joined onto the events feed.
  - SkillCorner
    - [Tracking](https://www.pitchkitjs.com/docs/data/skillcorner/tracking): Broadcast tracking at 10 fps — streamed out of a 90 MB file, and plotted in SkillCorner's own metres.
    - [Dynamic Events](https://www.pitchkitjs.com/docs/data/skillcorner/dynamic-events): Possessions, passing options, off-ball runs and pressure — SkillCorner's derived event model, 322 columns wide.
    - [Phases of Play](https://www.pitchkitjs.com/docs/data/skillcorner/phases-of-play): A match as a sequence of possessions — where each one started, where it got to, and whether it produced a shot.
  - Wyscout
    - [Events](https://www.pitchkitjs.com/docs/data/wyscout/events): Match events from the Wyscout open dataset — typed, filtered, plotted.
- [mplsoccer → PitchKit](https://www.pitchkitjs.com/docs/migration): The cheatsheet — every common mplsoccer call and its PitchKit equivalent.

## Optional

- [Full documentation](https://www.pitchkitjs.com/llms-full.txt): every narrative page above, concatenated as Markdown.
- [API reference](https://www.pitchkitjs.com/llms-api.txt): the generated per-symbol TypeDoc reference, kept out of the above because of its size.