RacingBars

Bar chart race made easy 🎉

RacingBars is an open-source, light-weight (~45kb gzipped), easy-to-use, and feature-rich javascript library for bar chart race, based on D3.js.

RacingBars is available for JavaScript, TypeScript, React, Vue and Svelte.

🎡 Try it now on the online playground.

📖 Documentations

Features

• Easy to use.
• Light-weight (~45kb gzipped).
• Highly configurable, with sensible defaults.
• Available for vanilla JavaScript,TypeScript, React, Vue and Svelte.
• Responsive / configurable chart size.
• Light and dark themes.
• Good looking default colors, also configurable with color maps or palettes.
• Customizable title, sub-title, caption and date counter. They all allow displaying calculated/dynamic values.
• Flexible handling for various data shapes and formats.
• Data manipulation for data transformation, cumulative sums and filling date gaps.
• Icons.
• Labels on the bars or outside.
• Groups with filters.
• Bar highlight and selection.
• Autorun or start manually.
• Allows looping.
• Optional fixed scale.
• Custom start/end dates.
• Allows changing speed.
• Controls for play/pause/skip-back/skip-forward (chart controls).
• Overlays for play/repeat (chart controls).
• Keyboard and mouse controls (chart controls).
• Multiple charts can be inserted in the same page.
• API to control the chart.
• Emits custom DOM events.
• Comprehensive documentation, with usage guides, examples gallery and an online playground.
• Open-source (MIT License).

Getting Started

Usage options include:

Option 1: Using a bundler

Install from npm

npm install racing-bars

then you can import it:

import { race } from "racing-bars";

const options = {
  title: 'My Racing Bars',
  // ... other options
};

race("/data.json", "#race", options);

Open in LiveCodes

Option 2: Load from CDN

ESM

<div id="race" style="height: 80vh"></div>
<script type="module">
  import { race } from "https://cdn.jsdelivr.net/npm/racing-bars";

  const options = {
    title: 'My Racing Bars',
    // ... other options
  };

  race("/data.json", "#race", options);
</script>

Open in LiveCodes

UMD

<div id="race" style="height: 80vh"></div>
<script src="https://cdn.jsdelivr.net/npm/racing-bars/racing-bars.umd.js"></script>
<script>
  const options = {
    title: 'My Racing Bars',
    // ... other options
  };

  // the UMD version provides the global object `racingBars`
  racingBars.race("/data.json", "#race", options);
</script>

Open in LiveCodes

Please refer to documentation website for usage, data preparation, chart options, API and more.

Framework Support

RacingBars works with vanilla JavaScript, TypeScript, React, Vue and Svelte. Dedicated docs for each:

JavaScript

import { race } from 'racing-bars';

race('/data/population.json', '#race', { title: 'World Population' });

Also available from CDN as ESM or UMD.

📖 JavaScript documentation

TypeScript

import { race, type Options } from 'racing-bars';

const options: Options = {
  title: 'World Population',
  topN: 10,
};

race('/data/population.json', '#race', options);

📖 TypeScript documentation

React

A wrapper React component is available as a default export from racing-bars/react.

import RacingBars from 'racing-bars/react';

export default function App() {
  return (
    <RacingBars dataUrl="/data/population.json" title="World Population">
      Loading...
    </RacingBars>
  );
}

All chart options are accepted as props, plus data, dataUrl, dataType, callback, elementId, className, and style.

📖 React documentation

Vue

A wrapper Vue 3 component is available as a default export from racing-bars/vue.

<script setup>
  import RacingBars from 'racing-bars/vue';
</script>

<template>
  <RacingBars dataUrl="/data/population.json" title="World Population">Loading...</RacingBars>
</template>

All chart options are accepted as props, plus data, dataUrl, dataType, callback, elementId, className, and style.

📖 Vue documentation

Svelte

Use the JS/TS library directly in Svelte 5 components with runes.

<script>
  import { onMount } from 'svelte';
  import { race } from 'racing-bars';

  let chart = $state(null);

  onMount(() => {
    race('/data/population.json', '#race', { title: 'World Population' }).then((r) => (chart = r));
    return () => chart?.destroy();
  });
</script>

<div id="race">Loading...</div>

📖 Svelte documentation

Examples Gallery

See gallery for usage examples.

Playground

Go to the online playground to try out the library.

Contribution

Contributions are welcome and highly appreciated.

Before contributing, please read the code of conduct.

Please open an issue to discuss your ideas before creating a pull request.

License

MIT License © Hatem Hosny.

Sponsor 💚

Please consider sponsoring the project to support its maintenance and continued development.