Component

XGTimeline

Cumulative expected-goals step chart for a match. Use it when the story is match flow over time, not final totals alone.

Stories

Canonical behaviors.

Empty State

No shot data. The chart stays explicit about the absence of a match story.

No shot data

Sparse Match

Very few shots. Useful for checking that the step geometry still reads honestly.

Mirrored Layout

Away xG plots downward from the axis. Useful when the page wants a clearer team split.

One-Team Dominant

Only one side shoots. The other line stays flat rather than inventing activity.

Extra Time

120-minute match flow with extra-time guides and shading.

Score Strip

Running scoreline strip for match-page treatments that need score context alongside xG.

Dark Theme

ThemeProvider restyles the chart without changing the shot model or team mapping.

Static Export

XGTimeline is part of the stable export union. Crosshair and methodology notes drop out, but the match-flow geometry stays deterministic.

Recipes

Composition patterns.

Methodology Notes

Use the shared chart-frame note seam for sample and modelling context instead of rebuilding prose around the card.

Opta-derived open-play and set-piece shots only

Penalties kept in the live chart; export excludes hover crosshair only

Cross-cutting

Shared concerns.

Choose XGTimeline

Use XGTimeline when the story is match flow across time. For static comparison of totals, use a simpler summary component instead.

Data Contract

Shots must already be normalized and assigned to the correct home and away team ids. The component does not infer match participants.

Layout

Ascending is the neutral default. Mirrored is a presentation choice when a stronger team split is more important than shared upward growth.

Composition

The chart already owns score-strip and shot-dot semantics. Surround it with match chrome rather than rebuilding those layers outside.

Export / Static

XGTimeline is part of the stable export surface, but only through the bounded export prop contract. The live crosshair and methodology notes stay outside that serialized path.

Theme

ThemeProvider should restyle labels, guides, and card chrome without changing the underlying match-flow geometry or team identity.

Responsive Behavior

XGTimeline is fundamentally a wide chart. On narrower widths the cumulative-step read and guide labels should survive before auxiliary annotation does.

Responsive

Width pressure.

Compact Container

The line read and time guides should hold up before score-strip and annotation density do.

Wide Match Panel

Wider layouts preserve more label separation and score-strip legibility.

Usage

Best-practice examples.

Minimal usage

Pass normalized shots plus explicit home and away team ids. The chart computes the running cumulative steps.

                    import { XGTimeline } from "@withqwerty/campos-react";

export function MatchXGTimeline({ shots, homeTeam, awayTeam }) {
  return <XGTimeline shots={shots} homeTeam={homeTeam} awayTeam={awayTeam} />;
}

Recipe-driven mirrored variant

Use named timeline recipes for the canonical match-page looks instead of rebuilding the same top-level layout combinations per page.

                    import { XGTimeline, xgTimelineRecipes } from "@withqwerty/campos-react";

export function MatchXGTimelineMirrored({ shots, homeTeam, awayTeam }) {
  return (
    <XGTimeline
      shots={shots}
      homeTeam={homeTeam}
      awayTeam={awayTeam}
      {...xgTimelineRecipes.mirroredScoreStrip.props}
    />
  );
}

API

Public surface.

Prop	Type	Default	Description
`shots`	`readonly Shot[]`	required	Array of normalized shot events with xG values.
`homeTeam`	`string`	required	Home team identifier; must match shot.teamId.
`awayTeam`	`string`	required	Away team identifier; must match shot.teamId.
`layout`	`"ascending" \| "mirrored"`	"ascending"	Chart layout variant.
`showAreaFill`	`boolean`	true	Show the semi-transparent fill between the step lines.
`showScoreStrip`	`boolean`	false	Show the running scoreline strip.
`showShotDots`	`boolean`	true	Show non-goal shot dots.
`showCrosshair`	`boolean`	true	Show the hover crosshair.
`teamColors`	`readonly [string, string]`	["#c8102e", "#1d428a"]	Custom [home, away] colour pair.
`markers`	`XGTimelineMarkersStyle`	—	First-class styling surface for shot markers.
`lines`	`XGTimelineLinesStyle`	—	First-class styling surface for cumulative step lines.
`guides`	`XGTimelineGuidesStyle`	—	First-class styling surface for halftime, full-time, and extra-time guides.
`areas`	`XGTimelineAreasStyle`	—	First-class styling surface for the area-fill layer.
`methodologyNotes`	`ChartMethodologyNotes`	—	Shared chart-frame note regions for sample and eligibility context.

`showCrosshair` and `methodologyNotes` are supported in the live React component, but they are intentionally outside the stable `ExportFrameSpec` contract.

Use with AI

LLM Prompt

Create a React component using Campos XGTimeline. Import XGTimeline and xgTimelineRecipes from @withqwerty/campos-react, keep shot normalization outside the component, show the smallest good usage first, then one recipe-driven mirrored or line-only variant.