Skip to content

Settings

Every chart type in RareCharts extends a shared base class. That means there's a set of options that work the same way everywhere — you don't need to re-learn them for each chart type.

This page documents those shared options. Chart-specific options (axis formatting, link types, bar orientation, etc.) are documented on each chart's own page.

Anatomy — the text slots

Every piece of text around a chart — the headline, the explanatory line, the legend, the attribution — is an option you pass to the constructor. The component renders it, in the system's typography and spacing, in the right place. You do not hand-build a title, a source line, or a caption in your own markup around the chart container. Feed the options and let the chart own the layout.

This matters because hardcoded structure drifts. A title written as a full sentence, a source without the Source: framing, an interpretive caption bolted on as a stray <div> — each one is a chart that no longer looks like the rest of the document. The slots below exist so the same data always reads the same way.

Each slot has a job. Use the right one and the chart composes correctly on its own.

Slot What it carries Content rule
title The headline — what the chart is. A short label in Title Case, roughly two to five words ("Revenue Dynamics"). Not a sentence. Never spell out the encoding here — "(bars)" / "(line)" belong to the legend, not the title.
subtitle The explanatory line — what against what. One sentence. The place for the full description, the units, and the timeframe that does not fit in a headline.
legend Series identity and mark. Identifies each series and which mark it uses — type: 'bar' renders a dot, 'band' a filled square, 'dashed' a dashed line, anything else a solid line. This is where "which one is the bars" is communicated. See Legend format below.
source Attribution. Always prefixed Source: and written in Title Case — 'Source: Internal Accounting', 'Source: Synthetic Demo Data'.
note Interpretation, disclaimers, caveats. One or two sentences of editorial context, rendered in muted type below the source. Use this instead of gluing a stray <div> under the chart container — same as the other slots, the component owns the placement and styling.

A correctly composed header and footer, then, is just options:

new RareCharts.DualAxes('#chart', {
  title:    'Revenue Dynamics',
  subtitle: 'Monthly revenue against year-over-year growth',
  source:   'Source: Internal Accounting',
  note:     'Growth is against the same month a year earlier; 2024 is restated.',
  legend: [
    { label: 'Revenue',    color: '#4f5be0', type: 'bar' },
    { label: 'YoY growth', color: '#e0564f' },
  ],
}).setData(series);

The reference for each slot's exact type and behavior follows below.

The constructor

All charts are created the same way:

new RareCharts.ChartType(selector, options)

selector is a CSS selector string ('#my-chart') or a direct DOM element reference. If the element is not found, the chart throws immediately — which is better than silently rendering into nothing and leaving you confused for twenty minutes.

options is a plain object. Everything is optional.

Header options

The chart header sits above the chart area and can contain a title, a subtitle, and a legend.

Option Type Description
title string Chart title, rendered as an uppercase <h5>
subtitle string Smaller text below the title; wraps onto as many lines as it needs (the title stays on one line)
legend array | string | HTMLElement Legend items (see below)
legendPosition 'right' Move the legend into a vertical column beside the chart
ariaLabel string Accessible name of the chart drawing (the <svg> gets role="img"). Defaults to the title and subtitle, joined with " — "; without them, "Chart". On MultiChart it names the grid (role="group")
legendInteractive boolean Default true: a legend item that names a series is a button that hides and shows it (see Interactive legend). false: every item is a plain label, and a series hidden from code leaves the legend
legendRescale boolean Default true: the value axes, a stack's percents and a ring's total follow the series shown. false: they keep every series, so a hidden one leaves its room
onLegendToggle function ({ name, visible, visibleNames }) => void, once per legend gesture, after the chart redraws

Without a title, subtitle or legend — and without timeframe buttons or the Log toggle — no header element is created: the chart starts right at the top of the container.

The header lays out by the width of the card, not of the window: on a card 460 px wide or narrower the timeframe buttons and the Log toggle move from beside the title to under the subtitle — a narrow card on a wide screen included.

Legend format

Pass an array of items and the chart renders them as a horizontal row of labeled indicators:

legend: [
  { label: 'Portfolio A', color: '#00c97a' },
  { label: 'Portfolio B', color: '#fa8c16' },
]

Each item supports:

  • label (or name) — display name
  • series — the series the item toggles, when its label is not the series' name; series: false keeps the item a caption
  • id — on Donut and Pie, the slice the item names, when the slices have ids
  • color — indicator color (the color of the series it names, else theme.accent)
  • type — the mark: 'bar' or 'dot' renders a round dot, 'band' a small filled square (a shaded range), 'dashed' a dashed line (as does dash: true); anything else, or nothing, a short solid line
  • an item with no type that names a dashed series — TimeSeries' comparison — gets a dashed swatch

For line charts, use the default line indicator. For bar and donut charts, use type: 'bar' — a dot reads as a filled mark rather than a stroke, which matches the shape of what you're labeling. Use 'dashed' for a forecast and 'band' for a confidence range.

legendPosition: 'right' places the legend in a vertical column to the right of the chart. Useful when you have many series and don't want the legend eating into the chart's vertical space. The chart area automatically adjusts its width; the navigator, your controls and the footer stay under the drawing, in that order.

Interactive legend

A legend item that names a series in the data is a toggle. It names one by series, else name, else label, so { label: 'Revenue' } toggles the series named "Revenue" and { label: 'Sales', series: 'Revenue' } does the same under another label. Every other item stays a label. When some items name series and one names none, the console says so once for that item — most likely a typo; give it series: false to keep it a caption. A string or element legend is your own markup, and the chart leaves it alone.

Gesture What it does
Click or tap; Enter or Space Hides or shows that series
Double click or double tap Keeps only that series; on the only series shown, brings all back
Show all Shows every series. The item is there while anything is hidden

A click that hides waits a quarter of a second for a second click, so the series you double-click to keep never flashes off. A click that shows, and Enter or Space, act at once. The toggles are buttons in the Tab order with aria-pressed, and the legend is a group named "Legend". The words "Show all" and "Legend" are fixed English.

A hidden series leaves the drawing, its end labels and markers, the crosshair and the tooltip. The time axis, the view, the timeframes, the navigator and the annotations stay where they are. Hide every series and the axes and the grid stay, with no marks. A hidden series stays hidden across setData, also while the new data lacks it.

What the rest of the chart does depends on the class and on legendRescale:

Chart legendRescale: true (default) legendRescale: false
Line, TimeSeries The Y axis fits the series shown The Y axis keeps every series in view
DualAxes Each axis fits its own series shown; an axis whose series are all hidden keeps their range, so its labels stay in its units Both axes keep every series in view
Bar, stacked The value axis runs to the tallest stack shown; stacked: 'percent' bars are shares of what is shown The axis keeps every series; percent bars are shares of the whole bar, and the top stays empty
Donut, Pie The ring closes over the slices shown; the total, the percents and the centre are theirs A hidden slice leaves its gap; the total and the percents stay of every slice

Sankey, Graph's flow view and MapFlow hide and show tie categories (linkTypes) the same way; a Sankey keeps its layout, so a hidden band leaves its gap at its nodes. In Graph's ego view the legend filters the traversal instead — see Graph. A MultiChart's own legend toggles the series of that name in every cell. Bar's category and date modes, HierarchicalBar, Gauge and Map draw one series or none: their legend is a caption.

onLegendToggle gets { name, visible, visibleNames } once per gesture, after the chart redraws: name is the series toggled (null for Show all), visible its state now (true after a double click), visibleNames the series shown, in data order. To set the legend from code, setSeriesVisible(names | null) — on Line, DualAxes, TimeSeries, the stacked Bar, Donut, Pie and MultiChart — shows the series named and hides every other series in the data; null shows them all. setLinkTypesVisible(types | null) does the same for tie categories on Sankey, Graph and MapFlow. Both redraw and return the chart, and neither fires onLegendToggle, so a page that mirrors one chart into another cannot loop. Call them after setData: they read the series from the data.

const chart = new RareCharts.Line('#chart', {
  legend: [
    { label: 'Revenue' },
    { label: 'Costs' },
    { label: 'Plan', series: false },   // a caption, not a toggle
  ],
  onLegendToggle: ({ visibleNames }) => saveShown(visibleNames),
}).setData(series);

chart.setSeriesVisible(['Revenue']);   // Revenue alone; no onLegendToggle
Option Type Description
source string | { text, href } | array | HTMLElement Rendered as a <cite> below the chart. Great for data attribution. Pass { text, href } to make it a link, or an array of parts to mix several links and plain text on one line — see below.
note string | HTMLElement Rendered as a <p class="rc-chart-note"> below the source, in muted type. For disclaimers, data caveats, and editorial context. Keeps interpretive text inside the component instead of as stray markup around the container.
controls HTMLElement | selector Your own controls that drive the chart — checkboxes, a time slider, a select. The element is moved inside the card, between the drawing and the source line, and gets the compact rc-chart-controls row style; its event listeners keep working. Keeps the controls visibly part of the chart instead of floating above it.
source: 'Source: The Truth',
note:   'Figures are unaudited and restated monthly.'

A single linked source:

source: { text: 'Source: Bloomberg', href: 'https://bloomberg.com' }

Multiple sources — some linked, some not. Pass an array of parts: a string renders as plain text, a { text, href } object as a link (in the source text color, underlined, opening in a new tab), a { text } object without href as plain text. Array sources wrap instead of truncating, so every attribution stays visible.

source: [
  'Source: ',
  { text: 'NASDAQ',    href: 'https://nasdaq.com' },
  ', ',
  { text: 'Bloomberg', href: 'https://bloomberg.com' },
  ', Internal calculations',     // plain, no link
]

Layout

Option Type Default Description
height number varies Total container height in px, with the title, subtitle, legend, buttons, navigator and footer included; see each chart's page for its default. On a narrow card those parts wrap and take more of it, and the plot gets what is left (chart.height). The plot keeps at least 80 px: when the parts would leave it less, the card grows past height by the difference, and returns to height once they fit again.
margin object per chart Space around the drawing area in px, { top, right, bottom, left }; a side you leave out keeps the chart's default. Donut, Pie, Gauge, Sankey and Graph fill the card and do not use it — except a vertical Sankey, which adds top and bottom to the height it computes for its card

Each chart sets its own margins around its axes — Line { top: 10, right: 64, bottom: 18, left: 0 }, Time Series { top: 16, right: 70, bottom: 28, left: 0 }, DualAxes a 64px gutter on each side; Map, MapFlow and MultiChart use none. Hiding an axis gives its gutter back, and annotations raise top to make room for their labels. A value axis's gutter that margin does not set grows to fit its widest tick or end label — $100,000 needs more than 64 px — and shrinks back to the class's width when the labels get narrower; a side you set stays as you set it. Set margin for a different frame:

new RareCharts.Line('#chart', {
  height: 320,
  margin: { top: 8, right: 50, bottom: 16, left: 40 },
})

Theme

Option Type Description
theme object Partial or full theme object. Merged with the active default.

Pass a theme object to override colors, the tooltip fonts, or the sizing defaults (line width, crosshair dots, markers, DualAxes bar opacity). The chart's own fonts and spacing are CSS variables. The full theme system is documented on the Styles page.

Quick example — apply the built-in dark theme:

new RareCharts.Line('#chart', {
  theme: RareCharts.darkTheme,
}).setData(data);

Or override just the accent color:

new RareCharts.Line('#chart', {
  theme: { accent: '#fa8c16' },
}).setData(data);

Colors

Chart colors follow a clear resolution order. Understanding it tells you exactly where to set a color and how overrides interact.

For each series, the chart resolves color in this order:

  1. color on the individual series object — highest priority
  2. theme.colors[index] — palette array, cycled by series position
  3. theme.accent — single accent fallback

The palette starts with blue, #1677ff, which is also the accent, then orange, #fa8c16. To change the default color across all single-series charts, override accent in the theme. To define a full multi-series palette, override theme.colors. On a page that sets the chart tokens — Rare Styles v0.7.2 does — the default palette is --chart-series-1 … --chart-series-6; a theme you pass wins over them. The full order is on Styles.

For multi-series charts, set color directly on each series in the data array:

chart.setData([
  { name: 'Revenue', color: '#1677ff', values: [...] },
  { name: 'Costs',   color: '#fa8c16', values: [...] },
]);

For single-series Line charts, lineColor is a shortcut that avoids wrapping flat data in a series object:

new RareCharts.Line('#chart', {
  lineColor: '#00c97a',
}).setData([{ date, value }, ...]);

Area fills inherit the series color; their opacity is the areaOpacity option (default 0.12, also per series on Line and DualAxes). DualAxes bars take the barOpacity option (default 0.35) — or set theme.barOpacity for every chart that shares the theme; Bar draws opaque bars.

Axis labels

Y axis tick labels support two levels of customization.

Prefix and suffix (Line, Bar and TimeSeries) attach a fixed string before or after each auto-formatted value:

yPrefix: '$'    // → $1.2M
ySuffix: '%'    // → 12.5%

Full format override replaces automatic formatting entirely on Line, Time Series and Bar. The bundled D3 is RareCharts.d3 — there is no global d3 on a page that loads only the library:

yTickFormat: v => RareCharts.d3.format(',.0f')(v) + ' units'

DualAxes has independent formatters for each axis — no prefix/suffix shortcuts, use y1TickFormat / y2TickFormat directly:

y1TickFormat: v => '$' + RareCharts.d3.format(',.2f')(v),
y2TickFormat: v => RareCharts.d3.format('+.1f')(v) + 'bp'

When yTickFormat is provided, it owns the tick labels: yPrefix, ySuffix and yFormat no longer apply to them. On Line it formats the end labels and the tooltip values too.

Short numbers: 50K, 1.2M

Without yTickFormat the value axis already shortens large numbers, by the step between its ticks: 0 50k 100k 150k, 0 0.5M 1M (D3’s SI prefixes: k, M, and G for billions). Value labels (valueFormat) and the default tooltips print full numbers, 50,000. To get the short form everywhere — or a capital K and B for billions — pass the same function to each:

const d3 = RareCharts.d3;
const short = v => Math.abs(v) < 1000
  ? d3.format(',~g')(v)                                          // 0.5, 500
  : d3.format('.3~s')(v).replace('k', 'K').replace('G', 'B');   // 50K, 1.23M, 2.5B, −42K

yTickFormat: short,
valueFormat: d => short(d.value),

For money, put the currency in the format: d3.format('$.3~s') gives $50k and −$42k. .3 keeps three significant digits; ~ drops trailing zeros.

Crosshair and tooltip

The crosshair is a vertical tracker that follows the cursor, snaps to the nearest data point on each series, and shows a tooltip. It is enabled by default on Line, TimeSeries, and DualAxes charts.

To disable it entirely (removes both the tracker line and the tooltip):

crosshair: false

Custom tooltip

tooltipFormat replaces the default tooltip with your own HTML. Build it from the classes of the default tooltip, and your rows look like the built-in ones:

tooltipFormat: ({ date, points }) => {
  const d = RareCharts.d3.timeFormat('%b %d, %Y')(date);
  return `<div class="rc-tooltip-header rc-tooltip-muted">${d}</div>` +
    points.map(p => `
      <div class="rc-tooltip-row">
        <span class="rc-tooltip-swatch" style="--rc-swatch-color:${p.color}"></span>
        <span class="rc-tooltip-label">${p.name}</span>
        <span class="rc-tooltip-value rc-num">${p.fmt} USD</span>
      </div>`
    ).join('');
}

points is an array of { name, series, type, color, date, value, fmt } — one entry per series that covers the hovered date; on DualAxes each also has axis, and a band has lower and upper in place of value (series is the name again, the role field every formatter shares — see Formatter arguments). fmt is the value already run through yTickFormat (or the default formatter), so you don't need to reformat it yourself.

The classes are optional. They are the ones the default tooltips use, they follow theme.tooltip and the page's tooltip tokens, and they are the supported hooks for page CSS:

Class What it is
rc-tooltip-header The line naming what is hovered. With rc-tooltip-muted: a date or a category on top, 13 px and muted. With rc-tooltip-title: a bold title (a region, a node)
rc-tooltip-row One row: a mark, a name and a value. Rows share the tooltip's width, so their values line up
rc-tooltip-row--plain A row without a mark
rc-tooltip-swatch The mark: a short line in --rc-swatch-color, which you set in the style attribute; without it, the text color
rc-tooltip-swatch--dashed, --band, --dot Other marks, with rc-tooltip-swatch: a dashed line, a square for a band, a dot for a bar, a slice or a region
rc-tooltip-label The name, in the tooltip's text color
rc-tooltip-value The value, right-aligned
rc-num Figures in the numeric font with tabular digits. Put it on the value; a value in words goes without it
rc-tooltip-note A line under the name, 13 px and muted: a change, a share. It goes inside the row, after the value
rc-tooltip-muted, rc-tooltip-sub Secondary text in the tooltip's muted color; rc-tooltip-sub is also small (11 px)

The string you return is inserted as HTML as is — escape anything that comes from your data (series names, labels from a CSV or an API) before putting it in. The default tooltips escape data themselves: a label such as <b> shows as text. This applies to every chart's tooltipFormat.

Tooltip styling

The tooltip text is 14 px on a 24 px line; the date on top and a note are 13 px. Names and words are in the chart's font, figures — values, percentages, dates in a row — in the numeric font, through .rc-num. theme.font sets the tooltip's words and theme.numericFont its figures. A visible tooltip is opaque.

Without colors of its own, the tooltip takes the page's --chart-tooltip-bg, --chart-tooltip-border, --chart-tooltip-text, --chart-tooltip-muted and --chart-tooltip-shadow (Rare Styles v0.7.2 sets them), so one rule recolors the tooltips of every chart on a page. For one chart, use theme.tooltip — here a dark tooltip on a light chart:

theme: {
  tooltip: {
    bg:     '#1a1a1a',
    border: '#333333',
    text:   '#e8e8e8',
    muted:  '#888888',       // dates and secondary rows
    shadow: '0 2px 12px rgba(0,0,0,0.5)',
    header: { text: null, bg: null },   // the date row; bg draws a band
  }
}

For structural changes (padding, border-radius, font size), use a selector that outranks the library's .rc-tooltip — the library appends its stylesheet to <head> when it loads, after any stylesheet already there, so a plain .rc-tooltip { … } loses the tie: .rc-chart .rc-tooltip { border-radius: 4px; }, .rc-chart .rc-tooltip-value { font-weight: bold; }. The crosshair line uses .rc-cross-line. All tooltip tokens and classes: Styles.

Formatter arguments

The formatters of Line, DualAxes, TimeSeries, Bar, HierarchicalBar, Donut and Pie, Gauge and Map — tooltipFormat, valueFormat, percentFormat, centerText — get the same role fields, whichever apply to what it formats: The relation charts keep their own payloads (table below): Graph, MapFlow and Sankey tooltips get one object each, and Sankey's valueFormat takes only the number.

  • label — the name of the item: a category, a slice, a tree node, a region;
  • value — the number drawn (null where there is none: an undisclosed node, a region without data);
  • date — the date of the point, on the time charts;
  • color — the colour the item is drawn in;
  • percent — its share of the whole, 0–1: of the category total (stacked bars), of all slices (Donut), of the tree's total (HierarchicalBar), of the range (Gauge);
  • series — the series name, where a chart has several.

Where they arrive follows one rule:

  • a formatter that gets an object made for it finds the role fields on that object, next to its own fields;
  • a formatter that gets a number, a data row or a tree node first keeps it, and gets the role fields as an object in the next argument — the second, or the fourth for Gauge's centerText(value, max, min).

So valueFormat: v => … written for an earlier version still works, and a formatter that needs more reads the second argument — here a HierarchicalBar prints each row's share of the total next to its value:

valueFormat: (node, { value, percent }) =>
  `${RareCharts.d3.format(',')(value)} · ${RareCharts.d3.format('.0%')(percent)}`
Class Formatter Arguments
Line tooltipFormat ({ date, points }) — each point { name, series, type, color, date, value, fmt }; a band has lower and upper instead of value
DualAxes tooltipFormat as Line; each point also has axis
TimeSeries tooltipFormat (row, { date, value, color, level }) — the row with its extra fields (open, volume…); level is the level drawn (null for plain rows). With compare also series and compare ({ date, value, change } or null); with band also band ({ lower, upper } or null)
Bar tooltipFormat, valueFormat (row, { label, value, color }); dated bars (row, { date, value, color })
Bar, stacked tooltipFormat, valueFormat (segment) — { i, name, cat, v0, v1, value, total } with label (= cat), series (= name), color, percent
HierarchicalBar tooltipFormat, valueFormat (node, { label, value, color, percent })
Donut, Pie tooltipFormat ({ label, value, percent, color })
Donut, Pie valueFormat, percentFormat (number, { label, value, percent, color }) for a slice; the center's value (number, { label, value })
Donut centerText (items, { label, value }) — the drawn items, the center label and the total
Gauge tooltipFormat ({ value, max, min, percent, color })
Gauge centerText (value, max, min, { value, max, min, percent, color })
Map tooltipFormat ({ feature, item, label, value, color }) — item is null for a region without data
Graph, Sankey, MapFlow node and link formatters one object each ({ node, links }, { link, source, target }…) — see their pages; Sankey's valueFormat(value) gets the number only

The axis formatters (yTickFormat, xTickFormat, y1TickFormat…) take only the tick value.

Names and labels

Two fields name things, and each has one job. A series is named by name: the lines of Line and DualAxes, the stacked Bar's series, a TimeSeries' seriesName. A part of one whole is named by label: a bar's category, a Donut or Pie slice, a HierarchicalBar node, a Map region. Formatters get the same two as series and label (see Formatter arguments), and a legend item shows its label and toggles the series its series, name or label names.

When parts of a stack become a whole of their own — a stacked bar's series totals drawn as a Donut — each series' name becomes a slice's label:

const slices = series.map(s => ({
  label: s.name,
  value: RareCharts.d3.sum(s.values, d => d.value),
}));

Timeframes and the view

Every chart with timeframes — Line, DualAxes, TimeSeries, the dated Bar, MapFlow and Graph's flow view — reads the same keys and options. The Time Series page shows them at work.

  • timeframeAnchor — the end every timeframe counts back from: 'dataEnd' (the default, the last data point), 'now', or a fixed date. With an anchor past the data, ALL, the zoom and the navigator run on to it. A relation chart reads a fixed anchor as a view bound: 1950 is the end of 1950.
  • Keys: ALL / MAX; the calendar TODAY, WTD, MTD, YTD (from the start of the anchor's day, week, month or year in the chart's timeZone); nH (real hours); nD, nW, nM, nY; { key, label, range } for a fixed period.
  • weekStart — the first day of a week for WTD and week buckets: 'monday' (default), 'sunday', any day name or 0–6.
  • 'CUSTOM' — a "Custom" button with From / To date fields and Apply; setTimeframe('CUSTOM', { range: [from, to] }) sets it from code. The panel is styled by rare-charts.css (.rc-range-custom, .rc-range-panel, .rc-range-label, .rc-range-input, .rc-range-apply) in the tooltip's colours, and is hidden in print.
  • onViewChange(fn) — fn(extent, { key, level }), once per button click and per brush drag: key is the timeframe key when a button or setTimeframe set the window (null for the brush, the wheel, setView), level the TimeSeries level drawn (null elsewhere).
  • setLoading(true | false) — a slim "Loading…" bar over the plot and aria-busy on the card, for a page that fetches data for a new window; the drawing stays until the new data comes.

The words "Custom", "From", "To", "Apply", "Loading…", "Hold Ctrl to zoom" and "Use two fingers to move" are fixed English.

Dates and time zones

The charts with a time axis — Line, DualAxes, TimeSeries, the dated Bar and Overview — and the time controls of Graph's flow view and MapFlow read their dates in one zone, the chart's timeZone: 'local' (the default, the reader's own zone) or 'UTC'. The zone decides how a date without a zone of its own is read, where the timeframes cut (TODAY, MTD, 1M…), and how the ticks, the tooltip and the navigator name the dates.

A date given as Is read as
A Date, epoch milliseconds, an ISO string with Z or an offset ('2024-03-01T12:00Z', '…+04:00') That instant, whatever the zone
A calendar string with no zone: '2024', '2024-03', '2024-03-01', '2024-03-01 14:30' (- or /, T or a space) That day and wall time in the chart's zone: local midnight by default, UTC midnight with timeZone: 'UTC'
Any other text As the browser's Date reads it; a row whose date cannot be read is dropped

A calendar step keeps the wall time and clamps the day of the month: 1M back from 31 March starts on 29 February in a leap year.

Use timeZone: 'UTC' when the data are UTC instants that stand for days — daily closes from an API, new Date('2024-03-01') (JavaScript reads a date-only string as UTC midnight), Date.UTC(…). In the default zone a reader west of UTC would see each such row on the evening before, named a day early. With 'UTC' every reader sees the same days, and date-only strings in annotations and setView() are read in UTC too:

new RareCharts.Line('#chart', {
  timeZone: 'UTC',
  annotations: [{ date: '2024-04-19', label: 'Halving' }],
}).setData(rows.map(r => ({ date: new Date(r.day), value: r.close })));

Your own xTicks and xTickFormat on a UTC chart need d3's UTC helpers — d3.utcFormat('%b %d'), d3.utcMonth.every(3) — because d3.timeFormat and d3.timeMonth work in the reader's zone. The defaults follow the chart's zone by themselves.

In local time, a day that crosses a daylight-saving change lasts 23 or 25 hours, so a daily bar on that day is a little narrower or wider. TimeSeries still counts such a step as a day when it works out the rows' interval.

The data adapters (fromJson, fromCsv…) take no zone: they read a date-only string as local midnight. For a chart with timeZone: 'UTC', map such a date to epoch milliseconds — date: row => Date.parse(row.date) reads '2024-03-01' as UTC midnight — or pass the rows' strings to setData without an adapter (Data import).

On Graph's flow view and MapFlow a tie's start and end may also be a period: a number below 10000 or 'YYYY' is a year, 'YYYY-MM' a month. As an end, a period runs to its last moment, so a tie ending '2024-01' lasts the whole of January. A full date is a point: an end of '2024-02-08' is the start of that day.

setData()

All charts expose a setData(data) method that accepts the chart-specific data format and triggers a render. You can call it multiple times — the chart will update in place without re-initializing. The chart keeps its own copy: the array you pass is never modified, dates are read (a Date, an ISO string or epoch milliseconds, in the chart's time zone) and sorted, and rows that cannot be read are dropped. An empty array clears the drawing. On charts with timeframes, the selected timeframe is applied to the new data, and a window the new data no longer reaches falls back to the full range.

const chart = new RareCharts.Bar('#chart', options);

chart.setData(initialData);

// Later — same chart, new data, no flicker
chart.setData(updatedData);

whenReady()

Every chart has whenReady(): a promise that resolves with the chart once it has drawn what it loads — Graph its queued requests and layout, Map and MapFlow the map geometry (it also resolves when the geometry fails to load; the error goes to the console). The other charts draw on setData(), so theirs is already resolved. Use it before measuring the drawing or taking a screenshot.

const map = new RareCharts.Map('#map', { geoUrl: '/data/europe.geojson' }).setData(rows);
map.whenReady().then(() => console.log('drawn'));

A chart in a hidden container

A chart created in a container that has no size yet — display: none, a closed tab panel or <details>, a dialog not yet open — draws nothing at first. It watches its container, and draws as soon as the container gets a size, so showing the container is enough: there is nothing to call. A chart created in a background browser tab draws when the tab is shown, as the browser holds its drawing frames until then. Measure the drawing after it is visible.

destroy()

Cleans up the chart: disconnects the resize observer, stops pending work (a font load, map geometry, graph requests), empties the container and removes the classes and inline sizes the chart added to it — anything your page set stays. Your own elements moved into the card (controls, a Graph details panel) go back where they were. After destroy() the chart draws nothing and calls none of your callbacks — onViewChange, onScaleChange, not even for a navigator drag that ends after it. Call this when removing a chart from the page to avoid memory leaks.

chart.destroy();

Defaults across charts

The options below exist on several classes, and their defaults are not all alike. Where they differ, they differ on purpose (maintainer decision, 2026-11-17): each class keeps the default that suits what it draws, and this table is the place to compare them. Each chart's page has the full list.

Option Default Where it differs
duration 650 ms: the entry of Line, Bar, HierarchicalBar, DualAxes, Donut, Pie, Gauge and Sankey Graph (ego, path, cluster): 500 ms for its moves; the first drawing does not animate. TimeSeries, Overview, Map, MapFlow and the flow view draw without an entry. animate: false draws at once; a reader who prefers reduced motion gets none
ease 'cubicOut' —
yTicks 4: Line, Bar; DualAxes y1Ticks, y2Ticks TimeSeries: 5
xTicks 6 on a date axis: Line, the dated Bar (DualAxes and TimeSeries draw 6 and take no option) Bar, horizontal: 4 on its value axis
yTickFormat By the step between ticks: 50k from 1,000, 0.5 below (Line, Bar; DualAxes y1TickFormat, y2TickFormat); on a log axis .3~s Line, with yFormat: 'auto' and values within ±1: a signed percent, +12.50%. TimeSeries: yFormat: 'currency', $ and ,.0f; yFormat: 'number' labels as Line
xTickFormat By the span in view: 14:00 up to 36 hours, Jan 05 up to 92 days, Jan up to a year, Jan '24 up to five years, 2024 beyond (Line, DualAxes, TimeSeries, the dated Bar) Bar, horizontal: its value axis, as yTickFormat
Values (end labels, tooltip) Three significant digits: 147, 1.23k (Line, DualAxes) Bar valueFormat: ,.2~f (1,234, 0.4). HierarchicalBar, Donut, Pie: , (1,234). Sankey: the reader's locale. TimeSeries tooltip: $ and ,.2f, or ,.2~f with yFormat: 'number'
curve 'monotone': Line, TimeSeries DualAxes: 'linear'. curveTension is 0 on all three
area false: Line and DualAxes, also per series, with areaOpacity: 0.12 TimeSeries and Overview: true, a gradient; a number is a solid fill at that opacity
Line width theme.strokeWidth, 2 Line and DualAxes take a series' own strokeWidth; TimeSeries has none
Value-axis gutter 64 px: Line, DualAxes (each side), the vertical Bar TimeSeries: 70. The horizontal Bar: 65 for its category labels, more for long ones. A gutter margin does not set grows to fit its widest label (see Layout)
barWidthRatio 0.72: Bar DualAxes: 0.65
nodeRadius 22: Graph ego, path and cluster The flow view: 18. MapFlow: 4, a place's dot
mobileBreakpoint 480 px of card width: Sankey turns vertical, MultiChart takes mobileColumns Every chart's header puts its range buttons under the subtitle on a card of 460 px or narrower; that width is not an option
centerLabel Donut: 'Total' (a Pie has no centre) Gauge: none
legendInteractive, legendRescale true on every chart with a series legend —
legendSymbols The flow view: a key row per node shape, named by its kind, when two or more shapes are drawn The dash and width rows show only with the words you give; false drops the key
timeZone 'local' on every chart with dates — (see Dates and time zones)

What is public

The contract is what these pages document: the classes with their documented options, methods and callbacks; the data shapes; RareCharts.d3 (a fixed part of D3, not all of it), the themes and the exported values on Installation; and the CSS hooks that Tooltip styling and Styles name — .rc-chart, .rc-tooltip and its row classes (.rc-tooltip-header, -row, -swatch, -label, -value, -note, -muted …), .rc-num, .rc-chart-controls, .rc-chart-note, .rc-cross-line, .rc-overview, Graph's .rc-graph-details and .rc-graph-tool, and the --rc-* variables. At 1.0 it freezes: from then on a change to it is a major version. Graph, Sankey and MapFlow are experimental and stay outside that promise.

Not part of it, and free to change in any release:

  • render(), the chart's internal redraw: a chart redraws itself on setData, on a resize and after its own methods;
  • the state a chart keeps on its instance (width, height, container, options, theme, margin, svg; TimeSeries' xScale and yScale) and every member whose name starts with _;
  • the classes on a chart's own parts — its bars, slices, regions, bands, nodes and ties — apart from the hooks above, the order of its elements, and the height and margin of MultiChart cells;
  • generateMockPrices, a helper for demos.

Complete example

new RareCharts.Line('#revenue-chart', {
  title:          'Monthly Revenue',
  subtitle:       'USD, last 12 months',
  source:         'Source: Internal accounting',
  legend: [
    { label: 'Actual',   color: '#1677ff' },
    { label: 'Forecast', color: '#aaaaaa' },
  ],
  height:         320,
  theme:          { accent: '#1677ff' },
}).setData(data);