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