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@alpha

Campos is currently shipping on the alpha npm channel, so install commands should pin @alpha until the default tag is promoted.

For the first alpha, prefer the npm command above. Some package managers that rely on npm's abbreviated metadata endpoint can lag on fresh scoped publishes and return temporary 404 errors.

Add @withqwerty/campos-schema when…

You want the canonical TypeScript types in your own app code.

Peer dependencies

react and react-dom 18 or 19.

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.
// If you want explicit TS types, install @withqwerty/campos-schema@alpha and annotate this as ShotEvent[].
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 — add this if you want typed data in your own app code. Install @withqwerty/campos-schema@alpha when you want the public schema in your own app surface.

@withqwerty/campos-adapters

Provider normalisation for Opta, StatsBomb, WhoScored, and Wyscout. Converts raw feeds into typed ShotEvent[], PassEvent[], and MatchLineups. Install @withqwerty/campos-adapters@alpha 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@alpha 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@alpha, 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 alpha 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 alpha hardening work