Getting Started

Build your first chart.

The shortest useful path is simple: install the React package, pass your data in, and render the chart.

Install

For the common React path, start here:

npm install @withqwerty/campos-react@beta

What ships with the install

All canonical types (Shot, PassEvent, FormationKey, etc.) are re-exported from @withqwerty/campos-react, so you typically don't need a separate @withqwerty/campos-schema install.

Peer dependencies

react and react-dom 18 or 19.

Add @withqwerty/campos-adapters if your data comes from Opta, StatsBomb, or similar feeds. Add @withqwerty/campos-static for server-side SVG / PNG export.

Fastest path

1. Bring your data

Campos expects normalised football data — shot arrays, pass arrays, or metric rows. Bring whatever your app already has. 

// Bring shots from your API, database, or fixture file.
// Campos expects x/y in 0–100 canonical pitch space.
// Types like Shot[] come from @withqwerty/campos-react.
const shots = await fetchShotsForMatch(matchId);
2. Render the chart

Pass the data in. Zero-config defaults handle pitch, legend, scale bar, stats, and empty state. 

import { ShotMap } from '@withqwerty/campos-react';

function MatchShotMap() {
  return <ShotMap shots={shots} />;
}
3. Style with callbacks

Express any styling logic as a callback. Constants and object maps work too for simple cases. 

<ShotMap
  shots={shots}
  markers={(shot) => ({
    fill: shot.xg > 0.3 ? '#e05252' : '#4a90d9',
    opacity: shot.outcome === 'goal' ? 1 : 0.6,
  })}
/>

What you get by default

Visual output

  • Pitch or chart scaffolding
  • Legends and scale treatments where supported
  • Responsive layout and empty-state handling

Football-specific behaviour

  • Chart semantics designed for football data, not generic plotting
  • Callback-first style props that accept any logic you can express in TS
  • Composable primitives for fuller match and season pages

What data format does Campos expect?

Campos expects data in canonical Campos space: x and y coordinates in a 0–100 range (own goal → opposition goal, left → right touchline). Bring your own normalisation step, or use the fixture examples in the showcase pages as a starting point.

For Opta / StatsBomb data

Use @withqwerty/campos-adapters to normalise raw provider feeds into typed Campos events. The adapters handle coordinate transforms, axis inversion, and qualifier parsing for you.

For aggregated data

ScatterPlot, RadarChart, and PizzaChart take plain metric arrays — no coordinate normalisation needed. Pass whatever fields your app already computes.

How the packages fit together

@withqwerty/campos-react

All chart components and styling logic. This is the library.

@withqwerty/campos-schema

Canonical TypeScript types. Re-exported from @withqwerty/campos-react, so you only need a direct install if you're using the schema without React (e.g., a Node data pipeline).

@withqwerty/campos-adapters

Provider normalisation for Opta, StatsBomb, WhoScored, and Wyscout. Converts raw feeds into typed ShotEvent[], PassEvent[], and MatchLineups. Install @withqwerty/campos-adapters@beta when your input starts as raw provider data.

@withqwerty/campos-stadia

Low-level Pitch and Goal primitives for custom football SVG composition when you want to build below the chart layer. Install @withqwerty/campos-stadia@beta for direct surface work.

@withqwerty/campos-static

Node-side SVG and PNG export for reports, OG cards, and scheduled image generation. Install @withqwerty/campos-static@beta, and add sharp if you need PNG output.

See complete examples

If you want to judge Campos as a real product layer instead of a single chart, start with the showcase.

Open the showcase

Current beta status

This is the honest package and product snapshot for the current release channel.

Available now

  • Published package surface: @withqwerty/campos-react, @withqwerty/campos-adapters, @withqwerty/campos-schema, @withqwerty/campos-stadia, and @withqwerty/campos-static
  • React chart surface spanning pitch charts, comparison charts, formations, stat-badge primitives, small multiples, and export helpers
  • Adapter coverage for major event providers such as Opta, StatsBomb, WhoScored, and Wyscout, plus sample/open-data-backed seams for Stats Perform, Impect, and Sportec, and narrower summary or shot adapters for Understat, FBref, and Sofascore
  • Static SVG and PNG export for the current supported chart set, plus the live docs site and showcase

Next focus

  • More battle-test recreations that pressure real football product surfaces
  • Callback-style parity across the remaining chart families
  • Tighter docs around page composition and recommended product patterns
  • Stronger export, reporting, and general pre-1.0 hardening work