Dual Axes Charts

Sometimes you need to plot two things on the same timeline that simply do not belong to the same scale. Revenue and headcount. Inflation and GDP. Price and spread. If you force them onto one axis, one series becomes unreadable, and the chart turns into a polite lie.

A dual-axis chart solves this by keeping a shared X axis (time) while providing two independent Y axes, so each metric is shown in its natural units. The goal is not to pretend the metrics are comparable. The goal is to compare when they move and how their dynamics relate.

In RareCharts, DualAxes is exactly that: a time-based chart with two vertical scales.

To illustrate a real-world use case, this example uses a finance-native story: a convergence (arbitrage) strategy based on the idea that two similar instruments that temporarily diverged in price will later converge again.

One concrete version of this story exists in government bonds, where a newly issued “on-the-run” Treasury can trade slightly richer than the previous “off-the-run” issue for a period of time. Traders may position for convergence by going long the cheaper issue and hedging the richer one, expecting the price gap to compress as the market normalizes.

In the chart, the right axis (Y1) shows the price index of the two instruments over time. The left axis (Y2) shows the spread between them. Prices and spread are different categories, so they get different axes. The chart stays readable, and the relationship stays visible.

Axis behavior and formatting

Both axes are configured independently. You can set titles (y1Title, y2Title), control tick formatting (y1TickFormat, y2TickFormat), and, when needed, override the visible ranges (y1Domain, y2Domain) to keep the chart stable and comparable across screenshots, reports, or multiple panels.

Axis titles are meant to be terse units (PRICE, N · K HLX). A title that would run past its axis margin is trimmed with an ellipsis — measured by rendered width, so a short label that fits is left alone — with the full text on hover and a one-time console hint. Set axisTitleMaxLength to cap it explicitly, or widen margin if you need more room.

In this example, the spread axis uses a signed format and treats very small values as clean zero, so you do not get the infamous +0.00 noise that makes charts look broken even when the data is fine.

Interaction

Dual Axes supports cursor inspection through a crosshair and a tooltip. The tooltip is fully customizable through tooltipFormat ({ date, points }), so you can present values in your product’s language instead of whatever generic tooltip someone thought was “good enough”.

Built-in timeframe controls

Because DualAxes is inherently time-based, it can also render the shared timeframe switcher in its own chart header:

const chart = new RareCharts.DualAxes('#chart', {
    timeframes: true,
    defaultTimeframe: '1Y',
});

chart.setData(series);

Available pieces:

• timeframes renders the built-in range buttons in the chart header.
• defaultTimeframe selects the initial visible range and active button.
• navigator: true renders the built-in overview strip with a brush under the main chart.
• setView([start, end]) sets any custom visible date window.
• getView() returns the currently visible [start, end].
• onViewChange(fn) lets external UI or a linked navigator stay synchronized.

Example:

const chart = new RareCharts.DualAxes('#chart', {
    timeframes: true,
    defaultTimeframe: '1Y',
    navigator: true,
});

Dual-axis charts are often implemented as a hack: two scales, mismatched formatting, confusing labels, and tooltips that quietly mix units. This component exists to make the dual-axis case predictable, explicit, and safe for real reporting: independent scales, consistent structure, and controlled formatting.

Annotations

DualAxes supports the full annotation API — vertical date markers (point and range) and horizontal reference levels (line and band) on either Y axis. Horizontal entries take an explicit axis: 'y1' | 'y2' so the value is mapped to the correct scale. See the dedicated annotations page for the full API.

Dual Axes chart options

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