Installation | Rare Digits Art

RareCharts ships as a single self-contained JavaScript file. No build step, no package manager, no fifteen dependencies with conflicting peer requirements. You add one script tag and it works.

D3 is bundled in. You do not need to include it separately.

Getting the file

From GitHub — clone the repo and use the prebuilt file:

git clone https://github.com/raredigits/rare-charts.git

Copy rare-charts.js wherever your project keeps static assets.

From CDN — load it directly, no download required:

<script src="https://cdn.jsdelivr.net/gh/raredigits/rare-charts@latest/rare-charts.js"></script>

For production, pin to a specific version. @latest is fine for prototyping, bad for anything that ships:

<script src="https://cdn.jsdelivr.net/gh/raredigits/rare-charts@v0.9.2/rare-charts.min.js"></script>

Where to put the script tag

Two standard options, both work fine.

Before </body> — the classic approach. The page renders first, then the script loads. Charts initialize against already-present DOM elements.

<body>
  <div id="chart"></div>
  ...
  <script src="/assets/rare-charts.js"></script>
  <script>
    new RareCharts.Line('#chart', { height: 260 }).setData(data);
  </script>
</body>

In <head> with defer — loads in parallel, executes after the DOM is ready. Same result, slightly cleaner separation:

<head>
  <script src="/assets/rare-charts.js" defer></script>
</head>
<body>
  <div id="chart"></div>
  <script defer>
    new RareCharts.Line('#chart', { height: 260 }).setData(data);
  </script>
</body>

The only rule: your chart initialization code must run after both the library and the container element are in the DOM. Either approach guarantees that.

Creating a chart

Every chart follows the same three-step pattern.

1. Add a container element:

<div id="my-chart"></div>

2. Create a chart instance, passing a selector and options:

const chart = new RareCharts.Line('#my-chart', {
  title:  'Revenue',
  height: 300,
});

3. Feed it data:

chart.setData(data);

Or chain steps 2 and 3:

new RareCharts.Bar('#my-chart', { height: 300 }).setData(data);

setData() can be called multiple times. The chart updates in place — useful for filters, date range selectors, or live data.

Sizing

Width is always 100% of the container. Make the container whatever width you need — the chart fills it and redraws automatically on resize. No window.addEventListener('resize', ...) required.

Height is set per instance via the height option. Each chart type has its own default (240–520px), but you almost always want to set it explicitly.

new RareCharts.Graph('#network', { height: 600 }).setData(data);

Available chart types

Class	Use case
`RareCharts.Line`	Time series, trend lines, multi-series performance
`RareCharts.TimeSeries`	Price time series with OHLCV data support
`RareCharts.Bar`	Category comparisons, ranked lists
`RareCharts.DualAxes`	Two metrics on different scales
`RareCharts.DualAxes` with mixed series	Bar + line overlay (combined charts are built on top of `DualAxes`)
`RareCharts.Donut`	Part-to-whole with center label
`RareCharts.Pie`	Part-to-whole, no hole (alias for Donut with `innerRadius: 0`)
`RareCharts.Gauge`	Progress toward a target
`RareCharts.Graph`	Force-directed network of nodes and links
`RareCharts.Map`	Choropleth and region-highlight geographic maps

All types share the same base options (title, subtitle, source, height, theme) — documented on the Settings page.

Using with Rare Styles

If your project uses Rare Styles, RareCharts picks up the CSS custom properties automatically — fonts, colors, and spacing stay consistent with the rest of your UI without extra configuration.

If you are using RareCharts standalone, the built-in defaults take over. Nothing breaks, nothing looks out of place.

Minimal working example

<div id="chart"></div>

<script src="/assets/rare-charts.js"></script>
<script>
  new RareCharts.Line('#chart', {
    title:  'Daily Active Users',
    source: 'Source: Analytics',
    height: 280,
  }).setData([
    { date: '2026-01-01', value: 1240 },
    { date: '2026-01-02', value: 1580 },
    { date: '2026-01-03', value: 1390 },
  ]);
</script>

One file, one div, one chart.