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.

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',
  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.

If none of these are provided, no header element is created — the chart starts right at the top of the container.

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: '#ff6200' },
]

Each item supports:

• label — display name
• color — indicator color
• type — 'bar' or 'dot' renders a square dot; anything else (or omitted) renders a short line

For line charts, use the default (line indicator). For bar and donut charts, use type: 'bar' — it renders a square dot instead of a line, which actually matches the shape of what you're labeling.

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.

Footer

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 standard blue, opening in a new tab). 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

The margin defaults are tuned for charts with a right-side Y axis (which is the default for line charts). If you're building something custom or have a left-side axis, you may want to adjust margin.left and margin.right.

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

Theme

Pass a theme object to override colors, fonts, or sizing defaults. 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: '#ff6200' },
}).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

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.

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

chart.setData([
  { name: 'Revenue', color: '#00aaff', values: [...] },
  { name: 'Costs',   color: '#ff6200', 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 controlled separately via areaOpacity (default 0.12). Bar fill opacity is barOpacity (default 0.35). Both can be set as chart options or through the theme.

Axis labels

Y axis tick labels support two levels of customization.

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

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

Full format override replaces automatic formatting entirely and works on all chart types:

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

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

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

When yTickFormat is provided, yPrefix, ySuffix, and yFormat are all ignored — the format function takes full ownership.

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:

tooltipFormat: ({ date, points }) => {
  const d = d3.timeFormat('%b %d, %Y')(date);
  return `<div>${d}</div>` +
    points.map(p =>
      `<div style="color:${p.color}">${p.name}: ${p.fmt}</div>`
    ).join('');
}

points is an array of { name, value, color, fmt } — one entry per series. fmt is the value already run through yTickFormat (or the default formatter), so you don't need to reformat it yourself.

Tooltip styling

Tooltip colors and shadow are controlled through theme.tooltip:

theme: {
  tooltip: {
    bg:     '#1a1a1a',
    border: '#333333',
    text:   '#e8e8e8',
    muted:  '#888888',
    shadow: '0 2px 12px rgba(0,0,0,0.5)',
  }
}

For structural changes (padding, border-radius, font size), target the .rc-tooltip CSS class directly. The crosshair line uses .rc-cross-line.

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.

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

chart.setData(initialData);

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

destroy()

Cleans up the chart: disconnects the resize observer and clears the container. Call this when removing a chart from the page to avoid memory leaks.

chart.destroy();

Complete example

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