Comparison · Intermediate

Bar race

Horizontal bars ranked at each time step that move to their new length and place as the steps play.

Open in playground

Use when: Telling how a ranking changed over time in a talk or a video, such as sales by brand per year
Avoid when: Readers need to compare exact values or ranks across time (a bump chart or a line chart does that better), or there is only one time step

Try it

Reduce motion

Bar race

Yearly sales by brand (thousand units)

2015

2026

Bar race data
Lumen	900, 1st
Aurora	663, 2nd
Halcyon	593, 3rd
Vertex	512, 4th, up 3 places
Pinnacle	501, 5th
Northwind	493, 6th, down 2 places
Kestrel	471, 7th, down 1 place
Quill	433, 8th, up 1 place

Hover over the chart, or Tab in and use the arrow keys to move between items. The numbers are sample data.

Variants

Named looks for this chart. Each one is the example above with a few options or fields changed. The CLI (ztd-charts example barRace --variant <id>) and the MCP server know the same names.

Top 5

Yearly sales by brand (thousand units)

First year

Yearly sales by brand (thousand units)

Without highlight

Yearly sales by brand (thousand units)

Code

BarRace.tsx

import { ChartCard, BarRace } from "ztd-charts";

const data = [
  {"brand":"Northwind","year":2015,"sales":420},
  {"brand":"Aurora","year":2015,"sales":380},
  {"brand":"Kestrel","year":2015,"sales":350},
  {"brand":"Halcyon","year":2015,"sales":300},
  {"brand":"Lumen","year":2015,"sales":120},
  {"brand":"Orbit","year":2015,"sales":260},
  // … 138 more rows
];

export function Example() {
  return (
    <ChartCard number="39" title="Bar race" subtitle="Yearly sales by brand (thousand units)" takeaway="Lumen climbs to 1st" level="intermediate" replay>
      <BarRace
        data={data}
        label="brand"
        value="sales"
        frame="year"
        top={8}
      />
    </ChartCard>
  );
}

Props

<BarRace> takes these props. Rows marked Common work the same on every chart.

30 props

Prop	Type	Default	Description
`data`RequiredAn array of objects. Pass CSV, REST or database rows as they areobject[]	object[]	-	An array of objects. Pass CSV, REST or database rows as they are
`label`RequiredItem name fieldstring \| (d, i) => string	string \| (d, i) => string	-	Item name field
`value`RequiredValue fieldstring \| (d, i) => number	string \| (d, i) => number	-	Value field
`frame`RequiredTime step field: a year, a date or any ordered key. Numbers and dates play in order, other text in the order it first appears. An item with no value in a step leaves the bars for that stepstring \| (d, i) => any	string \| (d, i) => any	-	Time step field: a year, a date or any ordered key. Numbers and dates play in order, other text in the order it first appears. An item with no value in a step leaves the bars for that step
`top`Bars in each step: the items with the largest valuesnumberDefault `10`	number	10	Bars in each step: the items with the largest values
`stepMs`Time per step while playing (ms)numberDefault `1000`	number	1000	Time per step while playing (ms)
`autoplay`Play from the first step when the chart scrolls into view. Off by default so a page does not move by itself; it never plays with reduced motion, where the controls step one at a timebooleanDefault `false`	boolean	false	Play from the first step when the chart scrolls into view. Off by default so a page does not move by itself; it never plays with reduced motion, where the controls step one at a time
`startFrame`The step shown first, and the one images and the first server paint show, as a step value such as 2021. Default: the last stepany	any	-	The step shown first, and the one images and the first server paint show, as a step value such as 2021. Default: the last step
`aggregate`How rows with the same step and label combine: "sum" adds them, "mean" averages, "last" keeps the last row, "count" counts rows"sum" \| "mean" \| "last" \| "count"Default `"sum"`	"sum" \| "mean" \| "last" \| "count"	"sum"	How rows with the same step and label combine: "sum" adds them, "mean" averages, "last" keeps the last row, "count" counts rows
`height`CommonHeight in px. Without it, each chart picks a default that fits its widthnumber	number	-	Height in px. Without it, each chart picks a default that fits its width
`width`CommonFixed width in px. Without it, the chart fits its parentnumber	number	-	Fixed width in px. Without it, the chart fits its parent
`highlight`CommonItem to highlight. An index, a name, an array, or "max" \| "min" \| "first" \| "last" \| "none"number \| string \| (number\|string)[] \| "max" …	number \| string \| (number\|string)[] \| "max" …	-	Item to highlight. An index, a name, an array, or "max" \| "min" \| "first" \| "last" \| "none"
`format`CommonValue format. "number" \| "integer" \| "percent" (values are already percents: 42 → "42%") \| "ratio" (0.42 → "42%") \| "compact" \| "currency" (KRW for Korean locales, otherwise USD; for another currency pass Intl options with currency) \| "decimal" or Intl.NumberFormat options"number" \| "percent" \| "compact" \| …	"number" \| "percent" \| "compact" \| …	-	Value format. "number" \| "integer" \| "percent" (values are already percents: 42 → "42%") \| "ratio" (0.42 → "42%") \| "compact" \| "currency" (KRW for Korean locales, otherwise USD; for another currency pass Intl options with currency) \| "decimal" or Intl.NumberFormat options
`unit`CommonUnit appended to values. For example "%" or "ms"string	string	-	Unit appended to values. For example "%" or "ms"
`locale`CommonLocale for numbers, dates and the text a chart writes itself (tooltips, screen reader sentences). "ko" or "ko-*" switches to Korean. Falls back to the ThemeProvider localestringDefault `"en-US"`	string	"en-US"	Locale for numbers, dates and the text a chart writes itself (tooltips, screen reader sentences). "ko" or "ko-*" switches to Korean. Falls back to the ThemeProvider locale
`animate`CommonEntry and update animationbooleanDefault `true`	boolean	true	Entry and update animation
`duration`CommonAnimation length (ms)number	number	-	Animation length (ms)
`easing`CommonMotion curve"spring" \| "easeOut" \| "easeInOut" \| "linear"Default `"spring"`	"spring" \| "easeOut" \| "easeInOut" \| "linear"	"spring"	Motion curve
`stagger`CommonDelay between items as they enter (ms)number	number	-	Delay between items as they enter (ms)
`reducedMotion`Common"auto" follows the OS setting. true always turns motion offanyDefault `"auto"`	any	"auto"	"auto" follows the OS setting. true always turns motion off
`animateOnView`CommonPlay when the chart scrolls into viewbooleanDefault `true`	boolean	true	Play when the chart scrolls into view
`showLabels`CommonLabels drawn on the chart (values and names)booleanDefault `true`	boolean	true	Labels drawn on the chart (values and names)
`tooltip`CommonShow tooltips. { template: "{label} · {value} · owner {owner}" } writes them: {label}, {value}, {series} or any other column of the row. \n starts a new line, and a line with an empty value is left outtooltipDefault `true`	tooltip	true	Show tooltips. { template: "{label} · {value} · owner {owner}" } writes them: {label}, {value}, {series} or any other column of the row. \n starts a new line, and a line with an empty value is left out
`syncId`CommonCharts with the same syncId show the hovered x together (line, area, bar, candlestick). <ChartGrid sync> sets one for every chart inside itstring	string	-	Charts with the same syncId show the hovered x together (line, area, bar, candlestick). <ChartGrid sync> sets one for every chart inside it
`ariaLabel`CommonName for screen readersstring	string	-	Name for screen readers
`description`CommonDescription for screen readers. Built from the data when omittedstring	string	-	Description for screen readers. Built from the data when omitted
`onHover`CommonRuns when hover or keyboard focus moves to another item(e: ChartEvent \| null) => void	(e: ChartEvent \| null) => void	-	Runs when hover or keyboard focus moves to another item
`onClick`CommonRuns on click, Enter or Space(e: ChartEvent) => void	(e: ChartEvent) => void	-	Runs on click, Enter or Space
`replayKey`CommonReplays the entry animation when it changesstring \| number	string \| number	-	Replays the entry animation when it changes
`theme`CommonChanges theme tokens for this chart onlyPartial<ChartTheme>	Partial<ChartTheme>	-	Changes theme tokens for this chart only

Try it

Variants

Code

Props

Also in Comparison