Pitch
The root component — owns the coordinate system and is responsive by default.
<Pitch> renders the pitch surface and markings, and provides the coordinate transform every
layer component reads from context. It's responsive by default (fills its container via
ResizeObserver); pass explicit width and height together to opt out. The four density
layers (<Heatmap>, <PositionalHeatmap>, <Hexbin>, <KDE>) paint to a <canvas> with no
server-rendered content to size against, so they need that opt-out; see
Responsive behaviour.
"use client";import { Pitch } from "@pitchkit/react";import { docsAppearance } from "./docs-appearance";/** Bare pitch, no marks — responsive by default (fills its container). */export function PitchBasic() { return <Pitch type="statsbomb" appearance={docsAppearance} />;}Props
| Prop | Type | Does |
|---|---|---|
type | pitch type id | Required. "statsbomb", "opta", "uefa", "skillcorner", "wyscout", "metrica" or "impect". Sets the coordinate system your data is read in. |
dimensions | overrides | The real extent of this particular pitch, for providers whose coordinates are metres, such as SkillCorner's pitch_length and pitch_width. Markings don't move. Overriding a normalised grid (Opta, Wyscout, Metrica) throws. |
orientation | "horizontal" | "vertical" | Defaults to horizontal. <VerticalPitch> sets it for you. |
width, height | number | Fixed pixel size. Provide both or neither. |
crop | CropWindow | Show part of the pitch, in the provider's own units. cropForHalf(dimensions) gives the attacking half. |
padding | ViewportPadding | Space around the pitch, in pixels. |
appearance | PitchAppearance | Structural options only; see below. |
className, style | — | Applied to the wrapper <div>. |
Vertical orientation
<VerticalPitch> is <Pitch orientation="vertical"> under a friendlier name (matching
mplsoccer's VerticalPitch) — useful for shot maps and attacking-third views.
"use client";import { VerticalPitch } from "@pitchkit/react";import { docsAppearance } from "./docs-appearance";/** Same pitch, vertical orientation — useful for shot maps and attacking-third views. */export function VerticalPitchBasic() { return <VerticalPitch type="statsbomb" appearance={docsAppearance} />;}Appearance
Colours are CSS variables (--pitch-surface, --pitch-stripe, --pitch-lines and others) —
set them once per theme, no per-instance props needed. See
Styling → Theming for the full list and
Styling → Tailwind for setting them with Tailwind utilities. stripes, goalType and linesOnTop are the
structural knobs, passed via the appearance prop:
<Pitch type="statsbomb" appearance={{ stripes: true, goalType: "box" }} />| Key | Does |
|---|---|
stripes | true for a sensible default count, or a number for exactly that many mown bands |
goalType | "line" (default) or "box" |
linesOnTop | Paints the markings above the layers instead of below them — mplsoccer's line_zorder |
linesOnTop is off by default so discrete marks sit on top of the lines. Turn it on for the
density layers (<Heatmap>,
<PositionalHeatmap>, <Hexbin>,
<KDE>), whose fills otherwise cover the markings underneath them. Only the
markings move — the grass surface and stripes always stay at the bottom.