Line charts are the default choice when you need to show change over time, compare multiple series, and make trends readable without forcing the reader to do arithmetic in their head. RareCharts supports a set of practical defaults and configuration options that help keep line charts clear even when the data is messy, multi-series, or formatted for business reporting.
A common use case is performance comparison: multiple instruments, portfolios, products, or metrics plotted on the same time axis, where the story is not “what is the exact number”, but “who moved, when, and how strongly”.
Data can be passed either as a single series or as multiple named series.
Single series format
const chart = new RareCharts.Line('#chart');
chart.setData([
{ date: '2026-01-01', value: 1.00 },
{ date: '2026-01-02', value: 2.5 },
{ date: '2026-01-03', value: -0.6 },
]);
When you pass data like this, the library will use options.seriesName (default: "Series") and options.lineColor (default: theme accent) to build the internal series object.
Multi-series format
const chart = new RareCharts.Line('#chart');
chart.setData([
{
name: 'Portfolio A',
color: '#00c97a',
values: [
{ date: '2026-01-01', value: 0.00 },
{ date: '2026-01-02', value: 0.010 },
],
},
{
name: 'Portfolio B',
color: '#ff3b5c',
values: [
{ date: '2026-01-01', value: 0.00 },
{ date: '2026-01-02', value: 0.006 },
],
},
]);
Dates are parsed via parseDate(…), so strings, timestamps, and Date objects are accepted as long as they can be converted to a valid date. A point whose value is missing (null, an empty string, true or false) or not a number is dropped as well: the line joins its neighbours instead of dipping to zero.
Built-in timeframe controls
Line charts can expose built-in timeframe buttons directly in the chart header. This is useful when the chart is date-based and you want users to jump between common windows such as one month, six months, one year, or the full history without wiring a separate control bar.
const chart = new RareCharts.Line('#chart', {
timeframes: true,
defaultTimeframe: '1Y',
});
chart.setData(data);
chart.setView([new Date('2025-01-01'), new Date('2025-12-31')]);
Available pieces:
timeframesrenders the built-in range buttons in the chart header.defaultTimeframeselects the initial visible range and active button.navigator: truerenders the built-in overview strip with a brush under the main chart.setView([start, end])sets any custom visible date window.setTimeframe(key)applies a timeframe from code — a key oftimeframesor a preset such as'1Y'— as its button does, and highlights the button.getView()returns the currently visible[start, end].onViewChange(fn)lets external UI stay synchronized with the chart’s active date window.scaleToggle: trueadds a Log toggle, pinned right in the same header row, above the Y-axis labels;onScaleChange(fn)reports each switch (see Logarithmic scale below).
If you want the built-in mini navigator as well, enable it explicitly:
const chart = new RareCharts.Line('#chart', {
timeframes: ['1M', '3M', '6M', '1Y', 'ALL'],
defaultTimeframe: '1Y',
navigator: true,
});
Styling and Themes
RareCharts inherits its look from the active theme (and aligns with Rare Styles when used together). You can still override per-series colors directly, and you can tune presentation without rewriting chart logic.
By default, the primary vertical axis is positioned on the right. This ensures consistent alignment across the layout and contributes to a professional dashboard appearance.
Two practical defaults matter here. First, the SVG width is always 100% of the parent container. Second, height is explicit and controlled per chart instance (height, default 240). That combination keeps layouts stable: the chart stretches horizontally with the page, and you decide how much vertical “reading room” it gets.
Configuration
The Line chart exposes a set of options that focus on business readability: formatting, tick density, baseline clarity, end labels, crosshair inspection, and line/area styling.
Layout and animation
height sets the chart height (default 240). margin controls the inner padding (top/right/bottom/left); by default, the right margin is wider (64) to accommodate the Y axis labels and end labels.
Animation is enabled on the first render by default (animate: true). You can control timing via duration (default 650 ms) and easing via ease (cubicOut by default; supported values include cubicOut, cubicInOut, linear). With prefers-reduced-motion: reduce the duration is 0. The lines draw in once per chart instance. Renders that land in the middle of it — the font load and the first resize right after setData, a later resize — carry the draw-in on from the share already drawn, on the new geometry, instead of starting it over.
Y axis formatting
RareCharts can format the Y axis automatically or explicitly.
yFormat supports auto (default), percent, and number. In auto mode, the chart treats data as percent-like when the maximum absolute value is ≤ 1 (for example, 0.12 becomes +12.00%). If you already store values as real numbers and still happen to be below 1, you probably want to force number to avoid accidental percent formatting. Number ticks follow the step between them: plain numbers below 1,000 (145 150 155 160, 0 0.5 1), SI prefixes from 1,000 on with one prefix for the whole axis (0.5k 1k 1.5k), and zero always as 0 — neighbouring ticks never print alike. End labels and tooltip values take three significant digits (147, −0.6, 1.23k). Percents keep a sign (+12.00%) on the ticks, the end labels and the tooltip; a log axis labels its powers 10 100 1k.
Zero is treated carefully: values with |v| < zeroEpsilon are printed as 0 (default 1e-6). This prevents the classic “-0.00%” or “+0.00%” artifacts that make charts look broken even when the data is correct.
You can also add yPrefix and ySuffix for units. If you need full control, provide yTickFormat: (value) => string and ignore the automatic formatting entirely — it then formats the ticks, the end labels and the tooltip values alike.
Tick density is controlled by yTicks (default 4). The number is a target, not a quota: ticks fall on round 1-2-5 steps inside the data range, so the axis never stretches past the data just to fit four steps. For minimalist displays, yLabelsOnly can be enabled (default true), keeping the axis visually restrained.
By default, the Y axis is rendered on the right side of the chart. If your layout or design system requires a left-aligned axis, you can override this behavior by setting:
yAxisPosition: 'left'
This moves the Y axis to the left while preserving all formatting and scaling logic.
Logarithmic scale
For long-horizon prices and indices, set yScale: 'log'. On a linear axis the same percentage move looks bigger the higher the series stands: the index below falls by half twice, in 2000 and in 2022, but on a linear scale the first crash is a ripple near the floor and the second a collapse. On a log scale equal percentage moves get equal height — both crashes look the same size, because they are. The demo opens on a linear axis; press Log to compare. Ticks fall on powers of ten (10, 100, 1k, 10k, 100k); a range narrower than two powers gets 1-2-5 steps instead (20, 50, 100). The margin above and below the data is a factor of its span rather than a share of the range, so both ends get the same room.
Zero and negative values have no place on a log scale: they are skipped (the line joins its neighbours) and the chart warns once in the console. Horizontal annotations at or below zero are dropped; an area fills down to the bottom of the plot.
The demo's Log toggle is built in: scaleToggle: true pins it to the top right of the chart header, above the Y-axis labels; timeframe buttons, when present, keep their place to its left. It is filled while the axis is logarithmic and transparent while it is linear; a click flips the scale, and onScaleChange(fn) tells the page when the reader switches. The same switch works on TimeSeries and DualAxes.
const chart = new RareCharts.Line('#chart', {
yScale: 'log',
scaleToggle: true, // a Log toggle; or { labels: { log: '…' } }
});
chart.onScaleChange(({ scale }) => console.log(scale));
The scale can also change from code, between data swaps — for example log on the full history, linear on the last year. setYScale() redraws, fills or clears the Log toggle and returns the chart, so chaining it before setData() changes both in one paint. Pass { silent: true } to skip the event:
chart.setYScale('log').setData(allHistory);
chart.setYScale('linear').setData(lastYear);
X axis formatting
xTickFormat is a function (date) => string. By default the labels follow the span in view, as on TimeSeries and Bar: '%H:%M' up to 36 hours, '%b %d' up to 92 days, '%b' up to a year, "%b '%y" up to five years, '%Y' beyond. To fix one format whatever the span, pass your own, for example:
xTickFormat: RareCharts.d3.timeFormat('%b %d') // Jan 05
// or
xTickFormat: RareCharts.d3.timeFormat('%Y-%m') // 2026-01
Baseline, grid, and “relative to zero”
The chart renders a grid and a zero baseline layer. This is not a decorative choice: performance charts are usually read relative to zero, so a clear zero reference is essential. (You can still customize how the baseline looks via theme styles.)
End labels
endLabels (default true) renders the last value for each series on the right edge. It is extremely useful in multi-series charts because it reduces legend-hunting: you look at the line, then you read its last value where the story ends.
If you disable it, the chart clears that layer.
Crosshair and tooltip
crosshair is enabled by default. It provides a vertical tracker line, dots at the nearest points, and a tooltip.
You can override tooltip content via:
tooltipFormat: ({ date, points: [{ name, series, type, color, date, value, fmt }, …] }) => html
One point per series that covers the hovered date; a band has lower and upper in place of value.
If you need a plain-text tooltip, return simple HTML with minimal markup, or keep the default and let the library handle it.
Legend
A legend item that names a series — by series, else name, else label — hides and shows it: a click toggles it, a double click keeps it alone, Show all brings every series back. A band is a series too. A hidden series leaves the plot, its end label and markers, the crosshair and the tooltip; the Y axis fits the series still shown (legendRescale: false keeps it on all of them), and the time axis, the timeframes, the navigator and the annotations stay. chart.setSeriesVisible(['Revenue']) sets it from code, after setData. More: Interactive legend.
Line shape, area fills, and markers
Line interpolation is controlled by curve (default monotone). You can use linear, basis, cardinal, step, and other D3 curve names supported by the library. If you choose cardinal, you can tune the smoothing via curveTension (0–1, default 0).
Area under the line can be enabled globally via area: true. areaOpacity defaults to 0.12. areaBaseline supports zero, min, or a numeric value; the fill always ends inside the plot.
Markers (point dots) are supported via markers (default false), with markerShape (default circle) and markerSize (default 4). Markers are useful when data is sparse or you want to emphasize sampling points, but they can clutter dense series, so they’re off by default for a reason.
Per-series overrides
In multi-series mode, you can override some style/shape settings per series, without affecting the rest. Supported per-series fields include curve, strokeWidth, strokeDash, area, areaOpacity, areaBaseline, and the marker fields: markers, markerShape, markerSize, markerFill, and markerStroke. This is the clean way to highlight a “main” series, or to render one series as an area while keeping others as plain lines.
Annotations
Line charts support event markers and reference levels via the annotations option — vertical lines and bands for date events (halvings, releases, freeze windows), horizontal lines and bands for reference levels (break-even, KPI targets, support zones). See the dedicated annotations page for the full API and behavior.
Line chart options
Common options shared by all chart types (title, subtitle, legend, legendPosition, source, note, controls, theme) are documented on the Settings page.
| Option | Type | Default | Description |
|---|---|---|---|
Layout |
|||
height |
number | 240 |
Chart height in px. Width is always 100% of the container. |
margin |
object | — |
Inner padding {top, right, bottom, left}.Defaults { top: 10, right: 64, bottom: 18, left: 0 }; with yAxisPosition: 'left' the Y axis takes a 64px gutter on the left, and the right one stays for the end labels. Hidden axes and end labels give their gutters back; annotations raise top to annotationLabelHeight + 4.
|
yAxisPosition |
'right' | 'left' |
'right' |
Side the Y axis is rendered on. End labels stay on the right either way. |
timeZone |
string | 'local' |
'local' or 'UTC': the zone a date string without a zone of its own is read in (the rows, annotations, the view bounds), the timeframes cut in, and the axis and the tooltip name dates in. A Date, epoch milliseconds or an ISO string with Z or an offset stays that instant. See Dates and time zones. |
timeframes |
boolean | array | — | Built-in timeframe buttons rendered in the chart header. Pass true to use the default set ['1M', '3M', '6M', '1Y', '2Y', 'ALL'], or pass a custom array of shortcuts and explicit ranges. |
defaultTimeframe |
string | object | — | Initial active timeframe used on first render when no explicit view has been set. |
defaultView |
array | — | Initial visible date range as [from, to]. An explicit alternative to defaultTimeframe; clamped to the data extent. If it misses the data, the chart shows the full range; set together with defaultTimeframe, defaultView wins. |
navigator |
boolean | object | — | Built-in overview strip with brush selection under the chart. Pass true for defaults or an object with overview options such as height, color, area, areaColor, brushColor, margin (defaults to the chart’s side margins) and axis (a time axis under the strip). On a multi-series chart the strip draws the first line series over the dates of all of them. |
Y axis |
|||
yFormat |
'auto' | 'percent' | 'number' |
'auto' |
In auto mode, values ≤ 1 are treated as percentages. Use 'number' to prevent accidental percent formatting. |
yTicks |
number | 4 |
Approximate number of Y ticks. Linear ticks stay inside the data range, so the actual count follows the step. |
yScale |
'linear' | 'log' |
'linear' |
Y scale type. 'log': power-of-ten ticks, multiplicative margin, values ≤ 0 skipped. Change it between data swaps with setYScale(). |
scaleToggle |
boolean | object | false |
A Log toggle pinned to the top right of the header, above the Y-axis labels: filled while the axis is logarithmic, transparent while it is linear; a click flips the scale. true or { labels: { log } }, labels.log being its text. Each switch fires onScaleChange. |
xTicks |
number | 6 |
Number of X tick marks. With the default date format, a span of fewer days gets one label per midnight in view (one at its start inside a single day), so a date is never repeated. |
yTickFormat |
function | — | (value) => string — overrides all automatic formatting: ticks, end labels and tooltip values. Default: ticks by their step — ,~f below 1,000, SI ~s (one prefix per axis) from 1,000, 0 for zero; end labels and tooltip to three significant digits (.3~r, .3~s from 1,000); percent +.2%; log ticks .3~s. |
yTickValues |
array | — | Explicit tick positions. Overrides yTicks. |
yPrefix |
string | '' |
Prefix added before each tick label (e.g. '$'). |
ySuffix |
string | '' |
Suffix added after each tick label (e.g. '%'). |
yLabelsOnly |
boolean | true |
Show only tick labels; suppress the axis line and tick marks. |
zeroEpsilon |
number | 1e-6 |
Values with |v| below this threshold are printed as 0. Prevents +0.00% artifacts. |
X axis |
|||
xTickFormat |
function | by span | (date) => string — controls X tick labels. |
Line style |
|||
curve |
string | 'monotone' |
D3 curve type: 'linear', 'monotone', 'basis', 'cardinal', 'step', etc. |
curveTension |
number | 0 |
Tension for the 'cardinal' curve, 0–1. |
strokeDash |
string | number[] | — | Dash pattern for every series: 'dashed', 'dotted', 'dashDot', 'longDash', or a raw stroke-dasharray such as '4,3' / [4, 3]. |
Area fill |
|||
area |
boolean | false |
Fill the area under the lines. |
areaOpacity |
number | 0.12 |
Fill opacity. |
areaBaseline |
'zero' | 'min' | number |
'zero' |
Where the fill ends: 'zero' — at 0, or the bottom of the plot when every value is above 0; 'min' — the bottom of the plot; a number — that value, kept inside the plot. |
Markers |
|||
markers |
boolean | false |
Show point markers at each data sample. |
markerShape |
string | 'circle' |
Marker shape. Supported: 'circle', 'square', 'diamond', 'triangle', 'cross'. |
markerSize |
number | 4 |
Marker radius in px. Defaults to theme.markerSize. |
Visibility |
|||
showGrid |
boolean | true |
Show horizontal grid lines. |
showXAxis |
boolean | true |
Show the X (date) axis at the bottom. Hiding it also collapses the bottom margin, so the plot runs flush. |
showYAxis |
boolean | true |
Show the Y (value) axis. Its side margin collapses once endLabels is off too — the axis and the end labels share that gutter. An explicit margin always wins. |
Interaction |
|||
crosshair |
boolean | true |
Vertical tracker line with dots at nearest data points and a tooltip. |
tooltipFormat |
function | — | ({ date, points }) => html — points is [{ name, series, type, color, date, value, fmt }], one per series covering the hovered date (a band has lower and upper instead of value); fmt is the value already formatted. All formatters: formatter arguments. |
endLabels |
boolean | true |
Render the last value of each series at the right edge. |
Annotations |
|||
annotations |
array | — | Event markers and reference levels. Vertical (date, from/to) and horizontal (value, yFrom/yTo) entries are mixed in the same array. See Annotations. |
annotationLabelHeight |
number | 22 |
Pixels reserved above the chart for vertical annotation labels. |
Animation |
|||
animate |
boolean | true |
Animate lines on first render. Plays only once per chart instance; a render in the middle of it (font load, resize) carries the draw-in on instead of restarting it. |
duration |
number | 650 |
Animation duration in ms. |
ease |
string | 'cubicOut' |
Easing: 'cubicOut', 'cubicInOut', 'linear'. |
Single-series shortcutsThese only apply when data is passed as a flat |
|||
seriesName |
string | 'Series' |
Series name shown in the crosshair tooltip. |
lineColor |
CSS color | theme accent | Line color. |
Per-series overrides (multi-series)Each series object in the data array can include these fields to override global settings: |
|||
name |
string | 'Series N' |
Series name — shown in the tooltip; also the key that keeps a series’ line in place on setData. The header legend is the separate legend option. |
color |
CSS color | theme palette | Series line color. |
strokeWidth |
number | 2 |
Line thickness in px. Defaults to theme.strokeWidth. |
strokeDash |
string | — | SVG dash pattern for this series only. |
curve |
string | global curve |
Curve type override for this series. |
area |
boolean | global area |
Fill area under this series. |
areaOpacity |
number | global areaOpacity |
Area fill opacity for this series. |
areaBaseline |
string | number | global areaBaseline |
Area baseline for this series. |
markers |
boolean | global markers |
Point markers on this series; false hides them when the global markers is on. |
markerShape |
string | global markerShape |
Marker shape: 'circle', 'square', 'diamond', 'triangle', 'cross'. |
markerSize |
number | global markerSize |
Marker radius in px. |
markerFill |
CSS color | series color |
Marker fill color. |
markerStroke |
CSS color | theme background | Marker outline color. |
values |
array | — | [{date, value}, ...] — the data points. |