DOCSEARCHbyAlgolia
Submit Docs

RacingBars

website·Indexed 32 days ago

https://racing-bars.hatemhosny.dev

A lightweight, open-source JavaScript library for creating highly configurable racing bar charts. It supports long and wide data formats, custom data transformations, and provides official wrapper components for React and Vue 3, as well as first-class TypeScript definitions.

Tokens
21.4K
Snippets
159
Records
202
Agent score
59%

What's inside RacingBars

  1. Overview of RacingBars library

    RacingBars is an open-source, lightweight (~45kb gzipped) JavaScript library based on D3.js used to create bar chart races. It is compatible with JavaScript, TypeScript, React, Vue, and Svelte.

  2. Racing Bars library overview and capabilities

    Racing Bars is a lightweight (~45kb gzipped), open-source (MIT License) library for creating animated bar chart races. It is compatible with vanilla JavaScript, TypeScript, React, Vue, and Svelte. Key capabilities include:

    • Responsive and configurable chart sizes with light and dark theme support.
    • Customizable titles, subtitles, captions, and date counters that support dynamic/calculated values.
    • Flexible data shape handling with built-in support for data transformation, cumulative sums, and filling date gaps.
    • Visual enhancements such as custom icons, bar labels (internal or external), grouping with filters, and bar highlighting/selection.
    • Playback controls including autorun, looping, speed adjustment, fixed scale options, and custom start/end dates.
    • User interface controls for play, pause, skip-back, and skip-forward via mouse, keyboard, or overlays.
    • Support for multiple charts on a single page, a programmatic API for chart control, and custom DOM events.

  3. Use TickDetails to access chart tick state in event callbacks

    The TickDetails interface provides metadata about the current state of a chart tick. This object is passed to event callbacks to allow developers to react to the chart's progression, animation state, and date positioning.
    interface TickDetails {
  allDates: string[]; // Array of all unique dates in the dataset, sorted ascending
  date: string;       // The current date as a 'YYYY-MM-DD' string
  isFirstDate: boolean; // true if the current date is the first date in the dataset
  isLastDate: boolean;  // true if the current date is the last date in the dataset
  isRunning: boolean;  // true if the chart is currently animating
}

  4. Understand default bar color behavior

    By default, RacingBars assigns a unique, consistent color to each bar name. If showGroups is enabled, all bars within the same group share the same color. Note that if the dataset contains a very large number of names or groups, colors may become visually similar.

  5. Use the Data interface for racing bar charts

    The racing bar chart uses a 'long' (tidy) data format. In this format, each object in the data array represents a single bar's state at a specific point in time. This is the primary data structure required to render the chart.
    const data: Data[] = [
  { date: '2017-01-01', name: 'Egypt', value: 96.44 },
  { date: '2017-01-01', name: 'Singapore', value: 5.61 },
];

  6. Use ApiCallback for chart event listeners

    The ApiCallback type defines the signature for callback functions used as chart event listeners. It accepts a single argument, tickDetails (of type TickDetails), which provides information about the current tick state of the chart. The function returns void.
    type ApiCallback = (tickDetails: TickDetails) => void;

  7. Display dynamic values in Racing Bars labels

    You can display dynamic values in the title, subTitle, DateCounter, and caption fields based on the current dataset and the date being displayed. This is achieved by utilizing the data function to inject values that change as the animation progresses.

  8. Install and use racing-bars with a bundler

    Install the racing-bars package via npm to use it within a project that utilizes a module bundler. Import the race function to initialize the racing bars component by providing the data source, the target element selector, and an options object.
    npm install racing-bars
    import { race } from "racing-bars";

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

  9. Fill missing date gaps in data

    By default, missing dates are skipped. To fill these gaps, use fillDateGapsInterval to define the time interval and fillDateGapValue to specify how to fill the missing values (e.g., using 'interpolate').
    const options = {
  fillDateGapsInterval: 'month',
  fillDateGapsValue: 'interpolate',
  valueDecimals: 2,
};

  10. Manually load and transform data

    For more complex transformations, use the loadData function to fetch the data first, transform it using standard JavaScript methods, and then pass the resulting array directly to the race function instead of a URL.
    import { loadData, race } from 'racing-bars';

const data = await loadData('/data/population.csv', 'csv');
const transformedData = data.map((d) => ({
  ...d,
  icon: `https://flagsapi.com/${d.code}/flat/64.png`,
}));

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

race(transformedData, '#race', options);

  11. Use racing-bars with TypeScript

    The library provides built-in TypeScript support. You can import the Options type to ensure your configuration object is type-safe.
    import { race, type Options } from 'racing-bars';

const options: Options = {
  dataType: 'csv',
  title: 'World Population',
};

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

  12. Provide in-kind contributions to RacingBars

    RacingBars accepts in-kind contributions of services or products that benefit the project and its users. In-kind contributors are recognized by name and logo on the credits page and in the project's GitHub README.