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 a release directly, no download required:
<script src="https://cdn.jsdelivr.net/gh/raredigits/rare-charts@v0.9.8_7/rare-charts.min.js"></script>
Always name the version. Releases after v0.9.8 are tagged v0.9.8_N, which jsDelivr does not treat as newer, so @latest still serves v0.9.8 — without HierarchicalBar, Sankey and MapFlow — until v0.9.9. The readable rare-charts.js sits next to the minified file under the same tag.
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 and runs after the HTML is parsed. Inline scripts ignore defer, so start the chart on DOMContentLoaded (deferred scripts run before it):
<head>
<script src="/assets/rare-charts.js" defer></script>
</head>
<body>
<div id="chart"></div>
<script>
document.addEventListener('DOMContentLoaded', () => {
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 (200–520px; HierarchicalBar, MultiChart and a vertical Sankey grow with their content), 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 |
Long date series with range buttons, zoom, pan and a navigator; extra fields (open, high, low, volume) reach tooltipFormat |
RareCharts.Overview |
The navigator strip on its own: a brush for picking a date window that drives charts you wire to it — Overview (standalone navigator) |
RareCharts.Bar |
Category comparisons, ranked lists |
RareCharts.HierarchicalBar |
A tree as an outline of bars: portfolio, org and budget breakdowns |
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 (Donut with innerRadius: 0 by default) |
RareCharts.Gauge |
Progress toward a target |
RareCharts.Graph |
Relationship networks: ego, path and cluster views, and money-trail flows (experimental) |
RareCharts.Sankey |
Flows between stages: budgets, money trails, balances (experimental) |
RareCharts.MultiChart |
Two to four charts of any type in one card, with a shared header, legend and footer |
RareCharts.Map |
Choropleth and region-highlight geographic maps |
RareCharts.MapFlow |
Flows between places over a map (experimental) |
All types share the same base options (title, subtitle, legend, source, note, controls, height — except HierarchicalBar and MultiChart, which size to their content — margin (axis charts; Donut, Pie, Gauge, Sankey and Graph fill the card), theme) — documented on the Settings page.
D3 and helpers in the bundle
RareCharts.d3 is the part of the bundled D3 that page code needs next to a chart — for formatters and small calculations. There is no global d3 on a page that loads only the library.
- numbers and dates as text:
format,formatPrefix,timeFormat,timeParse,utcFormat,utcParse; - arrays:
sum,min,max,extent,mean,range; - scales:
scaleLinear,scaleTime,scaleLog,scaleOrdinal; - colour:
color,rgb,hsl,interpolate; - calendar intervals:
timeDay,timeWeek,timeMonth,timeYear,utcDay,utcWeek,utcMonth,utcYear.
const d3 = RareCharts.d3;
yTickFormat: v => '$' + d3.format(',.0f')(v)
Before v0.9.8_6 RareCharts.d3 was the whole D3 namespace, which kept all of D3 in the bundle; the subset adds nothing the charts do not use themselves. A page that needs more of D3 — selections, shapes, geo — loads D3 itself.
RareCharts.generateMockPrices(days, startPrice) makes random price rows (date, value, open, high, low, volume) for demos and sketches. It is a demo helper, outside the stability guarantee: its output and signature may change in any release, and it may leave the bundle. Real pages pass their own data.
Exported utilities
RareCharts.VERSION— the version of the bundle on the page, such as'v0.9.8_7'.RareCharts.DOCS_URL— the address of these docs,'https://raredigits.art/charts'.RareCharts.defaultTimeframes— the range buttons thattimeframes: truedraws:['1M', '3M', '6M', '1Y', '2Y', 'ALL']. Build your own set from it:timeframes: [...RareCharts.defaultTimeframes.slice(0, -1), 'YTD', 'ALL'].RareCharts.defaultTheme,darkTheme,createTheme— the themes (Styles).RareCharts.fromJson,fromCsv,fromApi,fromArray— the data adapters (Data import).RareCharts.memorySource,linkPresets— Graph's in-memory data source and its link type presets (Graph).
Fonts and Rare Styles
RareCharts does not need Rare Styles or any other stylesheet. The chart CSS is bundled in with its own spacing and type variables, so a chart keeps its layout on any page, a blank one included.
The library loads no fonts. Charts use Fira Sans for text and Cousine for numbers when the page provides them, and the system sans-serif and monospace fonts otherwise. Rare Styles self-hosts both families, so a Rare Styles page needs nothing more. On any other page, load them yourself for the same look:
<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Fira+Sans:ital,wght@0,400;0,700;1,400&family=Cousine:wght@400;700&display=swap">
The charts read the page's chart tokens where it has them: the fonts from --chart-font-family and --chart-font-family-numeric, the colors from --chart-* (Styles). Rare Styles sets them since v0.7.2; on v0.7.1 and on other pages the charts take their own values. No Rare Styles version is required.
To change the type system, override the --rc-* variables with a selector that outranks the library's .rc-chart rule, such as :root .rc-chart — see Styles.
Strict Content Security Policy
The bundle adds its stylesheet to <head> as a <style> element. A Content Security Policy without 'unsafe-inline' in style-src blocks it, and the charts lose their layout. Serve the stylesheet as a file instead:
1. Take rare-charts.css of the same version as your bundle. Each release publishes it next to the bundle — https://cdn.jsdelivr.net/gh/raredigits/rare-charts@v0.9.8_7/rare-charts.css — if your policy allows that origin in style-src; otherwise save it with your other static files (the copy at /assets/charts/rare-charts.css is the one these pages document, v0.9.8_7) and take it again when you update the bundle.
2. Link it with the id rc-base-styles. The bundle finds the id and adds no <style> of its own:
<link id="rc-base-styles" rel="stylesheet" href="/assets/rare-charts.css">
If the stylesheet reaches the page another way — inside your own CSS bundle, say — turn the injection off before the bundle runs. Under such a policy an inline <script> is blocked too, so set it in a script file of your own (or one with the policy's nonce), loaded before rare-charts.js:
window.RareChartsConfig = { injectStyles: false };
Without the stylesheet at all the charts still draw, unstyled: the header and footer text take the page's color, and the Graph tool buttons are the page's plain buttons.
Everything else the charts style from script — sizes, positions, theme colours — goes through the DOM style API, which the policy allows. One thing it does block: colours written as style attributes into the markup of the built-in tooltips — a row's mark in its series colour, a link type in its own colour in the relation tooltips. Those then take the tooltip's own colours.
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.