Skip to content

Styles

RareCharts uses a two-layer styling system. Structure, layout and typography live in CSS. Colors, the tooltip fonts and a few sizing defaults live in a JavaScript theme object. They work independently, which means you can swap a theme without touching CSS, and you can override layout without touching the theme.

Layer 1: CSS structure

rare-charts.js automatically injects a small stylesheet into <head> when the library loads (a page under a strict Content Security Policy loads it as a file instead — see Installation). It handles:

  • The .rc-chart flex container (header with the title, subtitle, legend and range buttons → SVG → navigator → your controls → source and note, in that order)
  • Legend layout (horizontal row, or vertical aside when legendPosition: 'right')
  • The header layout by the card's width: .rc-chart is a size container (container: rc-chart / inline-size), and on a card 460 px wide or narrower the buttons move under the subtitle, whatever the window's width. The card takes its width from its parent — a block, a grid cell, a stretched flex item; in a box that shrinks to fit its content (an inline-block, an item of a flex row) give it a width, or it collapses
  • Tooltips: position and fade, size, weights and spacing of their rows
  • SVG axis label styles, end labels, markers
  • Spacing, the chart font, and the timeframe buttons — a page's button:hover background does not reach them, and the Log toggle keeps its fill on hover

RareCharts ships with its own typography and spacing defaults. The base stylesheet defines:

  • --rc-font-family: the page's --chart-font-family, else "Fira Sans", system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif
  • --rc-font-family-numeric: the page's --chart-font-family-numeric, else "Cousine", ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace
  • --rc-font-size: 16px
  • --rc-font-size-sm: 14px
  • --rc-space-xs, --rc-space-sm, --rc-space-md, --rc-space-lg: 4px, 8px, 16px, 32px

These variables live on .rc-chart, so the charts keep a consistent visual language even when embedded on a third-party site with a completely different type system. The chart sets font-family once, on .rc-chart; everything inside inherits it. To change a variable, use a selector that outranks the library's .rc-chart rule — the library appends its stylesheet to <head> when it loads, after any stylesheet already there, so a plain .rc-chart { … } on the page loses the tie: :root .rc-chart { --rc-font-family: Georgia, serif; }, or the chart's id.

The library loads no fonts. Fira Sans and Cousine are used when the page provides them — Rare Styles self-hosts both — and system fonts otherwise. Installation has a <link> that loads them on any page.

Colors are tokens. A chart has two kinds of color:

  • Role colors — the background behind labels, text, axis labels, axes, grid, crosshair, the range buttons, the focus ring, the tooltip, a map's empty regions and borders — are CSS variables, --rc-*, declared on .rc-chart. The SVG refers to them (fill="var(--rc-muted, #666666)") and the HTML reads them through CSS rules, so a chart follows its card, a page theme switch and print without a redraw.
  • Data colors — the accent, the series palette and every color you pass — are plain colors, read when the chart is built, at each setData and at each render. Formatters get them as #rrggbb, never as var(); a color you passed by name, such as 'steelblue', arrives as written.

Where colors come from

Each color resolves in this order, highest first:

  1. a color the chart's own theme sets — darkTheme, createTheme(…), any value other than the default. The chart writes it on its element as --rc-*, so it wins over the page;
  2. the page's chart tokens, --chart-*. Rare Styles v0.7.2 sets them on the page, on .card and on .card-inverted;
  3. older page tokens, only where earlier versions read them: --bg-color for the background; --text-color-light, --border-color, --primary-color, --primary-text-color and --white for the range buttons;
  4. the library's own value.

So a chart in a Rare Styles v0.7.2 .card-inverted reads light on the dark card, and a page without Rare Styles, or with v0.7.1, gets the library's values. The token behind each color is in the reference below. A page that changes --chart-series-* while a chart is on screen sees the new colors at the next setData or resize.

darkTheme sets colors of its own, so the page's tokens do not change it, but it does not paint the card: put the chart on a dark container. For a chart on a background of your own, restate the tokens there — On a host's background in Rare Styles shows how.

Layer 2: JS theme

The theme is a plain object that every chart reads at render time. In the default theme each color reads the page's chart token first and ends in the library's value:

const defaultTheme = {

  // ── Backgrounds ────────────────────────────────────────────────────────────
  bg:      'var(--chart-bg, var(--bg-color, #ffffff))',  // plates and halos behind labels
  surface: null,          // Graph node fills, flow lane bands: the background with 4% of the text

  // ── Structure ──────────────────────────────────────────────────────────────
  grid:      'var(--chart-grid-color, #e4e4e4)',   // horizontal grid lines, the Gauge track
  border:    'var(--chart-axis-color, #cccccc)',   // axis lines, zero baseline
  crosshair: '#aaaaaa',   // vertical hover line — subtler than border

  // ── Text ───────────────────────────────────────────────────────────────────
  text:  'var(--chart-text-color, #000000)',    // primary labels, the header and footer
  muted: 'var(--chart-label-color, #666666)',   // axis tick labels, secondary text

  // ── Accent and series palette ──────────────────────────────────────────────
  accent: 'var(--chart-series-1, #1677ff)',     // highlights, single-series default
  colors: [
    'var(--chart-series-1, #1677ff)',  // blue (the accent)
    'var(--chart-series-2, #fa8c16)',  // orange
    'var(--chart-series-3, #00c97a)',  // green
    'var(--chart-series-4, #ffcc00)',  // yellow
    'var(--chart-series-5, #cc44ff)',  // violet
    'var(--chart-series-6, #ff0000)',  // red
  ],

  // ── Typography: the tooltip's words and figures ───────────────────────────
  font:        'var(--rc-font-family, "Fira Sans", system-ui, -apple-system, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif)',
  numericFont: 'var(--rc-font-family-numeric, "Cousine", ui-monospace, SFMono-Regular, Menlo, Consolas, "Liberation Mono", monospace)',

  // ── Sizing defaults ────────────────────────────────────────────────────────
  // Charts use these as fallbacks when options are not passed explicitly.
  
  strokeWidth: 2,
  dotRadius:   3,         // crosshair dot radius
  markerSize:  4,         // per-point marker size
  barOpacity:  0.35,

  // ── Map ────────────────────────────────────────────────────────────────────
  map: {
    matchFill:     null,  // regions with data take the accent
    unmatchedFill: 'var(--chart-grid-color, #e8e8e8)',
    ocean:         'transparent',
    border:        'var(--chart-bg, #ffffff)',
    hoverBrighten: 1.3,   // hover: 30% towards white
    graticule:     null,  // the text at 8%
  },

  // ── Tooltip ────────────────────────────────────────────────────────────────
  tooltip: {
    bg:     'var(--chart-tooltip-bg, #ffffff)',
    border: 'var(--chart-tooltip-border, #e4e4e4)',
    text:   'var(--chart-tooltip-text, #000000)',
    muted:  'var(--chart-tooltip-muted, #666666)',
    shadow: 'var(--chart-tooltip-shadow, 0 2px 8px rgba(0,0,0,0.10))',
    header: { text: null, bg: null },
  },
};

A color you set in a theme is a plain color, '#e63946'; a key left at its default follows the page. defaultTheme.colors[0] passed as a series color is the chain too: the chart draws it as the page's series color. Read the colors a chart drew from its formatter arguments, not from defaultTheme.

Built-in themes

Two themes ship with the library.

RareCharts.defaultTheme — the page's chart tokens where it has them; otherwise light: clean grays, a blue accent and the palette above. Works anywhere.

RareCharts.darkTheme — dark plates and labels for a dark card: deep blacks, muted grids, an orange accent (#ff6200) for a single series and map regions. It keeps the default palette for several series. It does not paint the card — the demo below sits on a black panel.

new RareCharts.Line('#chart', {
  theme: RareCharts.darkTheme,
}).setData(data);

The result:

Creating a custom theme

RareCharts.createTheme(overrides, base) merges your overrides with a base theme — the default one unless you pass another — and returns a complete theme object. You only need to specify what you want to change:

const brandTheme = RareCharts.createTheme({
  accent:  '#e63946',
  colors:  ['#e63946', '#457b9d', '#a8dadc', '#1d3557'],
  numericFont: '"JetBrains Mono", monospace',   // the tooltip's figures
  tooltip: {
    bg:     '#1d3557',
    border: '#457b9d',
    text:   '#f1faee',
  },
});

new RareCharts.Bar('#chart', {
  theme: brandTheme,
}).setData(data);

createTheme does a shallow merge for top-level keys and a deep merge for tooltip, tooltip.header and map, so you can override individual tooltip properties without losing the rest.

To adjust a built-in theme, pass it as the base:

const theme = RareCharts.createTheme({ tooltip: { bg: '#000000' } }, RareCharts.darkTheme);

Spreading it instead — { ...RareCharts.darkTheme, tooltip: { bg: '#000000' } } — merges the tooltip onto the light defaults: black text on a black tooltip.

Applying theme to multiple charts

Create the theme once and reuse it:

const theme = RareCharts.createTheme({ accent: '#fa8c16' });

new RareCharts.Line('#chart-a', { theme }).setData(dataA);
new RareCharts.Bar('#chart-b',  { theme }).setData(dataB);
new RareCharts.Donut('#chart-c', { theme }).setData(dataC);

All three charts will use the same colors, fonts, and tooltip styling. Consistency without repetition.

Partial overrides

You don't have to use createTheme for minor tweaks. Passing a partial object directly to the theme option works the same way — it merges with the default theme automatically:

// Just change the grid color
new RareCharts.Line('#chart', {
  theme: { grid: '#f0f0f0' },
}).setData(data);

Theme token reference

Colors

The theme's colors, the CSS variable each one reaches, and the page token it reads when the theme leaves it at its default:

Token CSS variable Page token Default Dark Used for
bg --rc-bg --chart-bg, then --bg-color #ffffff #0a0a0a Plates behind last-value and annotation labels, label backdrops and halos, the Graph tool buttons and full screen (the tooltip background is tooltip.bg)
surface --rc-surface mixed from --chart-bg and --chart-text-color null: the background with 4% of the text, #f5f5f5 on white #141414 Graph node fills, flow lane bands
grid --rc-grid --chart-grid-color #e4e4e4 #666666 Horizontal grid lines, the Gauge track
border --rc-border --chart-axis-color #cccccc #888888 Axis lines, zero baseline
crosshair --rc-crosshair — #aaaaaa #3a3a3a Hover tracker line
text --rc-text --chart-text-color #000000 #e8e8e8 Title, subtitle, legend and source; primary labels, node labels; navigator strip tint and window
muted --rc-muted --chart-label-color #666666 #888888 Axis tick labels, the note, secondary text, fallback link color
accent --rc-accent --chart-series-1 #1677ff #ff6200 Single-series default, highlights, map regions with data, the Log toggle when on
colors — --chart-series-1 … --chart-series-6 #1677ff, #fa8c16, #00c97a, #ffcc00, #cc44ff, #ff0000 same Multi-series palette, node group colors

The range buttons and focus rings have CSS variables only. A theme with a background of its own (darkTheme) sets the buttons from its colors: labels in muted, borders in border, the pressed button in text on bg.

CSS variable Page token Default Used for
--rc-control-text --chart-control-text, then --text-color-light #666666 Range button labels
--rc-control-border --chart-control-border, then --border-color #cccccc Range button and Graph tool borders
--rc-control-hover-border --chart-control-hover-border, then --primary-color #000000 The border of a hovered or pressed range button
--rc-control-active-text --chart-control-active-text, then --primary-text-color #000000 The label of a hovered or pressed range button
--rc-control-active-bg --chart-control-active-bg, then --white #ffffff The background of the pressed range button
--rc-focus-ring --chart-focus-ring currentColor Keyboard focus rings: legend items, the Graph breadcrumbs and "+N more" list, Graph, Sankey and flow nodes, flow and MapFlow ties

On Rare Styles v0.7.2 the focus rings are blue, its --focus-ring-color; elsewhere they take the text color.

Typography

Token Default Used for
font var(--rc-font-family, "Fira Sans", system-ui, …, sans-serif) The tooltip's words: names, labels, titles
numericFont var(--rc-font-family-numeric, "Cousine", ui-monospace, …, monospace) The tooltip's figures: values, percentages, counts (.rc-num)

The chart CSS also defines the following container-level variables:

CSS Variable Default Used for
--rc-font-family --chart-font-family, then "Fira Sans", system-ui, …, sans-serif Chart font: title, legend, source, note, buttons, SVG text, the tooltip
--rc-font-family-numeric --chart-font-family-numeric, then "Cousine", ui-monospace, …, monospace Values and axes, the navigator's time labels (10px), the tooltip's figures
--rc-font-size 16px Chart title
--rc-font-size-sm 14px SVG text, subtitle, legend, source, note, buttons
--rc-space-xs 4px Header row gap, timeframe button gap and radius
--rc-space-sm 8px Legend dots, tooltip and button padding, source margin
--rc-space-md 16px Header and legend column gap, tooltip and button padding
--rc-space-lg 32px MultiChart grid gap, right-hand legend offset

Line heights are the chart's own on any page: 24px for the title, the tooltip rows and the controls, 1.3 for the source.

These are RareCharts variables, not host-site variables: a host's spacing scale does not change a chart. The fonts read the page's --chart-font-family and --chart-font-family-numeric first — Rare Styles v0.7.2 sets them — then fall back to Fira Sans and Cousine. If you want a different type system, override the variables as above. Of the theme's fonts, font sets the tooltip's words and numericFont its figures; the chart text follows the variables.

Sizing

Token Default Used for
strokeWidth 2 Line width of Line, DualAxes and Time Series lines
dotRadius 3 Radius of the crosshair dots (Line, DualAxes)
markerSize 4 Per-point markers (Line, DualAxes)
barOpacity 0.35 DualAxes bar fill opacity; Bar draws opaque bars

The tokens are fallbacks: an option wins when it is set — a series' strokeWidth, markerSize on the chart or a series, DualAxes' barOpacity. The Time Series line has no width option; set the token.

Map

Token CSS variable Default Dark Used for
map.matchFill — null: the accent, #1677ff null: the accent, #ff6200 Regions with data and no color of their own (the matchFill option wins)
map.unmatchedFill --rc-map-unmatched-fill var(--chart-grid-color, #e8e8e8) #1e1e2e Regions without data (the defaultFill option wins)
map.border --rc-map-border var(--chart-bg, #ffffff) #444455 Region borders (the borderColor option wins)
map.ocean — transparent transparent Background behind the land (the oceanColor option wins)
map.hoverBrighten — 1.3 1.2 Hover on a region with data: its fill moves (factor − 1) of the way towards white; a very light fill darkens a little instead (the hoverFill option wins; 1 turns it off)
map.graticule --rc-map-graticule null: the text at 8%, rgba(0,0,0,0.08) on black rgba(255,255,255,0.06) The 10° grid drawn with the graticule option

createTheme merges map deeply, so createTheme({ map: { matchFill: '#fa8c16' } }) recolors every map. With matchFill left null, changing accent recolors maps too.

Tooltip

The tooltip sub-object colors every built-in tooltip, independently from the main chart. By default the tooltip is a light popover, on a dark card too:

Token CSS variable Default Dark Used for
tooltip.bg --rc-tooltip-bg var(--chart-tooltip-bg, #ffffff) #1a1a1a Background
tooltip.border --rc-tooltip-border var(--chart-tooltip-border, #e4e4e4) #2e2e2e 1px border
tooltip.text --rc-tooltip-text var(--chart-tooltip-text, #000000) #e8e8e8 Names, values, titles, links
tooltip.muted --rc-tooltip-muted var(--chart-tooltip-muted, #666666) #888888 The date on top, notes, percentages, counts — every secondary line
tooltip.shadow --rc-tooltip-shadow var(--chart-tooltip-shadow, 0 2px 8px rgba(0,0,0,0.10)) 0 2px 12px rgba(0,0,0,0.55) Box shadow
tooltip.header.text --rc-tooltip-header-text null null Color of the header — the line naming what is hovered
tooltip.header.bg --rc-tooltip-header-bg null null A band behind the header, across the top of the tooltip

The header is the date on top in Line, DualAxes, TimeSeries and a dated Bar, the category in a stacked Bar, and the bold title in Map (a region without a value), MapFlow, Sankey and Graph; Bar, HierarchicalBar, Donut, Pie and Gauge show rows only. With header.text left null each keeps its role: a date is muted, a title bold in tooltip.text.

A dark tooltip on a light chart sets the secondary color too:

theme: {
  tooltip: { bg: '#1a1a1a', border: '#333333', text: '#e8e8e8', muted: '#888888' },
}

The tooltip inherits these variables from the chart's element: a theme writes its own values there, and without them the tooltip reads the page's --chart-tooltip-*. A theme's fonts arrive the same way, as --rc-tooltip-font (words) and --rc-tooltip-font-numeric (figures).

The tooltip text is 14px on a 24px line, the date on top and the notes 13px; a visible tooltip (.is-visible) is opaque. Its rows carry classes — .rc-tooltip-header, .rc-tooltip-row, .rc-tooltip-swatch, .rc-tooltip-label, .rc-tooltip-value, .rc-tooltip-note, .rc-num and the others listed under Custom tooltip, and .rc-tooltip-kind, .rc-tooltip-section, .rc-tooltip-small and .rc-tooltip-body in the relation tooltips. A page rule that outranks the library's .rc-tooltip restyles any of it, colors included: .rc-chart .rc-tooltip { border-radius: 4px; }. A plain .rc-tooltip { … } loses the tie, as with .rc-chart above.