# Race bar chart

> Bars that re-rank as values change over time, with play, pause and a scrubber.

Component · Pro · https://lodeui.com/components/race-bar-chart

## When to use

- Telling how a ranking changed over time: market share by year, top products by week.
- Presentations and landing pages where the motion is the story.

## When not to use

- Reading exact values at a moment: use a bar chart with a period picker.
- Trends of one or two series: use a line chart.

## Installation

```bash
npx shadcn@latest add @lode/race-bar-chart
```

Pro: needs a Lode API key and the `@lode` registry in components.json. See https://lodeui.com/docs/cli.

npm dependencies: motion, lucide-react

## Usage

```tsx title="example.tsx"
import { RaceBarChart } from "@/components/ui/race-bar-chart";

const frames = [
  { label: "2024", values: { Search: 420, Social: 180, Direct: 260 } },
  { label: "2025", values: { Search: 460, Social: 340, Direct: 280 } },
  { label: "2026", values: { Search: 480, Social: 520, Direct: 300 } },
];

export function Race() {
  return <RaceBarChart frames={frames} top={5} />;
}
```

## API reference

### RaceBarChart

Ranked bars that tween between frames and re-order as they overtake.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| frames | `RaceFrame[]` | – | { label, values: Record<name, number> }, in time order. |
| top | `number` | `8` | Bars shown at once. |
| speed | `number` | `1400` | Milliseconds per frame. |
| colors | `Record<string, string>` | – | Colour per name; others use the chart palette. |
| format | `(n) => string` | – | Value at the end of each bar. |
| autoPlay | `boolean` | `true` | Start when the chart scrolls into view. |
| loop | `boolean` | `false` | Start again after the last frame. |
| rowHeight | `number` | `34` | Height of each row in px. |

## Keyboard interactions

| Keys | Action |
| --- | --- |
| Tab | Move to play and the time slider |
| Arrow keys | Step through time on the slider |
| Enter / Space | Play, pause or replay |

## Accessibility

- Bars are a list; the current period is announced politely as it changes.
- The slider has the period as its value text.

## Motion

- Values ease between frames and rows slide to their new rank.
- With reduced motion nothing autoplays and rows jump instead of sliding.

## Responsive behavior

- Name column shrinks on narrow screens; bars fill the rest.

## Performance

- One animation frame loop while playing, stopped when paused or finished.

## Notes for AI

- Every frame should list the same names; a missing name counts as 0.
- Keep frames to a few dozen; tweening makes them feel continuous.

## Related

- [Bar chart](https://lodeui.com/components/bar-chart) — Bars that grow in and morph between datasets, with a hover readout.
- [Line chart](https://lodeui.com/components/line-chart) — Multi-series lines with legend toggles, crosshair and shared tooltip.
- [Sankey flow](https://lodeui.com/components/sankey-flow) — Volumes flowing between stages as ribbons. Hover a stage to trace everything that passes through it.