Skip to content

Multi Charts

MultiChart combines two to four charts inside a single block with a shared title, subtitle, legend, and source footer. Each panel is an independent chart instance of any chart class — a Line, a Bar, a Donut, a Sankey, a Map and so on — arranged in a CSS grid.

Usage

const mc = new RareCharts.MultiChart('#container', {
  title:    'A Selloff Takes Shape',
  subtitle: 'Selling intensified on the second day of trading',
  source:   'Source: Bloomberg',
  columns:  2,         // 1 – 4 columns
  chartHeight: 200,    // height of each chart in px

  charts: [
    {
      type:  'Line',
      title: 'Brent Crude',
      data:  brentData,
      options: { yPrefix: '$', lineColor: '#1677ff' },
    },
    {
      type:  'Line',
      title: 'DXY Dollar Index',
      data:  dxyData,
    },
    {
      type:  'Bar',
      title: 'Monthly Volumes',
      data:  volumeData,
      options: { barColor: '#1677ff' },
    },
  ],
});

Each child chart is accessible via mc.charts[index] after construction, so individual panels can be updated independently — either way the grid keeps the panel’s last data for a rebuild at the breakpoint (see below):

mc.charts[0].setData(newBrentData);

Or update all panels in a single call — one dataset per panel, in the order of charts:

mc.setData([brentData, dxyData, volumeData]);

Responsive layout

MultiChart automatically switches to a single column when the container width reaches the breakpoint (default 480 px). No extra configuration needed — on desktop you get two columns, on mobile everything stacks vertically.

Use mobileOptions on any chart descriptor to override that panel's options when the narrow layout is active. The most common use case is restoring hidden Y-axis labels on panels that suppressed them in the side-by-side view:

{
  type: 'Bar',
  title: 'Women',
  options: {
    showYAxis: false,   // hidden on desktop — Men chart already shows the labels
    margin: { left: 0 },
  },
  mobileOptions: {
    showYAxis: true,    // restored on mobile — chart stands alone
    margin: { left: 100 },
  },
}

The narrow layout depends on the container width alone — at most mobileBreakpoint px — not on the column counts: a one-column grid on a desktop screen still uses options. When the container crosses the breakpoint — a window resized past it, a phone turned — the grid switches its columns and rebuilds each panel that has mobileOptions: the old chart is destroyed and a new one is made with the options of the new side and given the panel’s last data, so every key applies, height and margin included. The rebuilt panel is a new instance: read it from mc.charts[i] again rather than keeping a reference, and expect state set through its own methods (a y scale, a view window) to start over from its options.

Side-by-side horizontal bar charts are a natural fit for group comparisons where labels are shared. Suppress the Y axis on panels after the first to keep things clean:

When you need a third panel, the span field on a chart descriptor stretches that cell across all grid columns — a clean way to place a summary chart above two detail panels:

Shared legend

The grid's own legend works across the cells. An item that names a series of any cell — by series, else name, else label, as on a single chart — is a toggle: a click shows or hides the series of that name in every cell, a double click keeps only that series, and "Show all" brings everything back. The series can come from any class: a line, a stacked bar, a slice, a Sankey link type. An item that names no series stays a caption.

const grid = new RareCharts.MultiChart('#prices', {
  legend: [{ label: 'Brent' }, { label: 'WTI' }],
  onLegendToggle: ({ name, visible, visibleNames }) => console.log(name, visible, visibleNames),
  charts: [
    { type: 'Line', title: 'Daily',   data: [{ name: 'Brent', values: daily.brent },   { name: 'WTI', values: daily.wti }] },
    { type: 'Line', title: 'Monthly', data: [{ name: 'Brent', values: monthly.brent }, { name: 'WTI', values: monthly.wti }] },
  ],
});

grid.setSeriesVisible(['Brent']);   // every cell, without onLegendToggle; null shows all

onLegendToggle fires on the grid only, and legendRescale goes down to every cell that does not set its own. A cell's own legend acts on that cell alone, until the next gesture on the shared one: use the shared legend when the cells draw the same series.

MultiChart options

Common options shared by all chart types (title, subtitle, legend, legendPosition, source, note, controls, theme) are documented on the Settings page.

The grid is a group (role="group") for assistive technology, named by ariaLabel, else by the title and subtitle joined with " — ". Each cell’s drawing is named by its own ariaLabel, title or subtitle in options, else by the cell title, else "Chart".

Option Type Default Description
Layout
columns 1–4 2 Number of grid columns on desktop.
mobileColumns number 1 Column count when the container is at or below mobileBreakpoint.
mobileBreakpoint number 480 Container width in px at which the grid switches to mobileColumns.
chartHeight number 200 Height of each chart in px. A child’s own options.height wins; a cell title adds its line above the chart.
gap number | string 32px Grid gap between cells — a px number or any CSS value.
animate boolean true Passed through to every child chart — set false to render all cells without entry animation.
Charts
charts array [] Array of chart descriptor objects — see table below.

Chart descriptor fields

Each object in the charts array defines one panel:

Field Type Default Description
type string 'Line' Chart class to instantiate for this cell, by its name: 'Line', 'Bar', 'TimeSeries', 'DualAxes', 'HierarchicalBar', 'Donut', 'Pie', 'Gauge', 'Sankey', 'Graph', 'Map' or 'MapFlow'. Without type (or with null) the cell is a Line. Two classes are not cells: 'Overview', the navigator strip (use navigator: true on a time chart), and 'MultiChart' (a grid does not nest). They and any other value draw a Line and warn in the console once per cell — a wrong case such as 'bar' included.
title string — Label shown above the cell in small uppercase; also the accessible name of the cell’s drawing when its options give no ariaLabel, title or subtitle.
span number — Column span for this cell. Set to the number of grid columns (e.g. span: 2) to stretch it full width.
data array — Passed to setData() immediately after construction.
options object — Forwarded to the child chart constructor: every option of the cell’s class applies. The grid sets height (chartHeight), animate and theme (the grid’s) unless these options set them. Under the bottom axis of Line, Bar, DualAxes and TimeSeries it also sets margin.bottom: 26 — also with showXAxis: false — unless margin.bottom is set; the other classes keep their own margin.
mobileOptions object — Merged over options while the container is at or below mobileBreakpoint wide, whatever the column counts. Supports all the same keys as options, height and margin included. Crossing the breakpoint rebuilds the panel with the options of the new side and its last data, so mc.charts[i] is then a new instance.