# Bar Chart Race — `bar-chart-race@1.0.0`

The racing bar chart: your names and numbers over the years, bars overtaking each other until a winner emerges.

Type your entries and their values for each period (years, months, weeks) and watch them race: bars grow and slide past each other, values tick up and the period rolls over in the corner. Choose the title, the units, how many bars are on screen, a dark or light theme and a colour palette. The sample figures are made up; replace them with your own.

- Kind: text; status: published; digest sha256:8750200e31d0d5be57f15b1e0f0c911b7463452b51c45960ad78f3dfada936e4
- Role: Data animation (Canvas 2D, full frame): a ranked bar chart that animates over time.
- Implementation: canvas2d; entry `src/bar-chart-race.js`
- Files: https://aipixelwizard.com/registry/bar-chart-race/1.0.0/<path> (`LICENSE`, `asset.json`, `demo.js`, `index.html`, `src/bar-chart-race.js`)
- Manifest JSON: https://aipixelwizard.com/api/v1/visuals/bar-chart-race/versions/1.0.0
- Runnable demo: https://aipixelwizard.com/registry/bar-chart-race/1.0.0/index.html (open over http; it imports sibling packages by relative path)
- Dependencies (exact): `apw-runtime@1.0.0` (demo) — Demo harness.

## Exports
- `createBarChartRace({ entries, periods?, title?, subtitle?, prefix?, unit?, decimals?, visible?, palette?, theme?, badges?, background?, duration?, intro?, hold?, fontFamily? }) => { draw(ctx, { time }, width, height), valuesAt(time), ranksAt(time), periodAt(time), timing }` — The race. entries are { name, values[] } with one value per period; draw paints the whole frame for a time in seconds.
- `parseRaceData(text) => { name, values }[]` — Reads compact text: 'Apples 42 48 55; Bananas 50 52 54' (rows split by ; or new lines).
- `parsePeriods(text, count) => string[]` — Period labels from text; a single year counts up ('2019' gives 2019, 2020, …).
- `PALETTES: { vivid, pastel, neon }` — The built-in bar colours (or pass your own array, or a color per entry).
- `THEMES: { dark, light }` — Background and text colours.

## Parameters
- `title` (text, default "Fruit sold at the market") — Title
- `subtitle` (text, default "Tonnes per year (sample figures)") — Subtitle
- `data` (text, default "Apples 42 48 55 58 61 66; Bananas 50 52 54 60 70 72; Cherries 12 20 35 52 68 85; Mangoes 30 45 50 52 55 57; Grapes 35 38 40 44 50 62; Kiwis 20 22 30 41 45 49; Lemons 25 27 28 31 40 43") — Data: One entry per row, rows separated by ; — a name, then one number per period. Example: Apples 42 48 55; Pears 30 45 50
- `periods` (text, default "2019") — Periods: One label per number: 2019 2020 2021, or Jan Feb Mar, or with commas when labels have spaces (Week 1, Week 2). A single year counts up.
- `prefix` (text, default "") — Before values: For example $ or €.
- `unit` (text, default " t") — After values: For example k, % or  pts.
- `decimals` (integer 0–2, default 0) — Decimal places
- `visible` (integer 3–12, default 7) — Bars on screen
- `theme` (select one of dark | light, default "dark") — Theme
- `palette` (select one of vivid | pastel | neon, default "vivid") — Colours
- `badges` (boolean, default true) — Initials on bars

## Composition
- Inputs: Entries with one value per period, period labels, the race duration. Time in seconds for each frame.
- Outputs: Draws the whole frame on a 2D canvas (or only the chart over your own background with background: false).
- Coordinates: Fills the canvas it is given, any aspect ratio; title top left, the period bottom right.
- Lighting: None.
- Timing: draw is a pure function of time: 0.8 s for the bars to grow in, the periods spread evenly, then 1.5 s on the final standings.
- Works with: gradient-background, kinetic-title, rolling-counter
- Data, names and titles are treated as private: not stored in shared packs unless you choose to include them.
- The panel's Data box holds up to 200 characters; in code, pass as many entries and periods as you like.
- System fonts differ between computers; pass fontFamily and load the font first for identical renders.

## Output and loop
- 1080×1080, 30 fps, 12 s, procedural
- Seamless loop: no — A race from the first period to the last, holding on the final standings.
- Verified 2026-10-05 in Chrome 154.0.8037.97 headless on Linux 7.0.0-38-generic (x64), Node 22.14.0 (Canvas 2D); deterministic: yes

## Use it
New project: Create the race once with your entries and periods, then each frame call race.draw(ctx, { time: frame / fps }, width, height).

Existing project: Copy src/bar-chart-race.js. Build entries from your data (or parseRaceData for quick text), and draw onto your 2D canvas or an overlay canvas above a WebGL scene.

Reuse ideas:
- "Most popular over the years": a dozen entries, a value per year, visible: 10, and a 30-second duration.
- Business update: the light theme with a $ prefix and k unit for monthly sales by region.
- Over your own background: draw a Gradient Background first, then the race with background: false.

## Limitations
- Values glide smoothly between the numbers you give; the chart does not show real values in between periods.
- Negative values are drawn as zero.

## License
MIT. Copyright (c) 2026 AI Pixel Wizard. Released under the MIT License. See LICENSE in this folder.

Provenance: Adapted from the owner's threejs-sketches/data-information/leaderboard-shuffle (MIT), rebuilt for AI Pixel Wizard in October 2026 as a 2D bar chart race with your own data: labelled bars, smooth overtakes, ticking values, an animated axis and period, and the frame/time contract.