Styling and themes

Style changes presentation. It never changes data meaning or transition meaning: a style can recolour an already-declared colour mapping, but it cannot decide to map a field to colour.

import { d3ChartStyle } from "visdelta/chart-style";

await transition(from, to, {
  target: "#chart",
  chartStyle: d3ChartStyle
});

Structural presetsCopy Anchor Link

Pass a chart style to the transition. Both endpoints use the same style.

import { paperChartStyle } from 'visdelta/chart-style';

const change = await transition(from, to, {
  target: '#chart',
  chartStyle: paperChartStyle,
});

chartStylePresets collects them by key (d3, paper, dark, editorial). The runtime scopes each preset to its own .vd-style-* root, so transitions on one page can use different styles. Bars keep square corners in every style.

Page theme tokens are inherited. A preset's local .vd-style-* declarations override inherited values; tokens the preset does not define continue to inherit. For example, Paper keeps its light surface and dark neutral ink on a dark page, while the default D3 style follows page tokens. More specific application CSS can still override a preset. Explicit chart colors, palettes and schemes take precedence over the style's default mark ink or categorical palette.

Choose a preset above to restyle five chart types at once; the shared slider seeks all five transitions.

Define a structural styleCopy Anchor Link

A chart style sets spacing, margins, grid policy, domain lines, title placement and legend placement:

import { defineChartStyle } from 'visdelta/chart-style';

const compact = defineChartStyle({
  key: 'compact',
  tickSpacing: { x: 56, y: 44 },
  legendPosition: 'right',
  plot: { grid: 'horizontal', margin: { top: 48, right: 88 } },
});

The default legendPosition: 'top' draws the legend in a block above the canvas, outside the chart's SVG, so it does not count toward the chart's width or height. 'right' keeps the legend inside the canvas, in its right margin.

Values merge in order: neutral defaults, the chart module's own defaults, then the style's overrides. An authored spec.margin is the final override. Margins are preferred spacing, not fixed reservations: whitespace adapts to the container while axis text keeps its size. A transition shares plot margins across its route; space for a top or right legend opens and closes with playback. In Fit mode, top-legend space also change the remaining canvas height.

Use a stable module reference for a mounted chart. A style contains functions such as axisTitle, so it is not a JSON configuration. Selecting a different module requires creating a replacement transition or sequence; resize() refreshes dimensions and CSS tokens, not structural style rules. Apply the last requested progress to the replacement before showing it.

A custom key scopes the root class but does not generate CSS. Its module sets structure; add scoped CSS tokens separately if it needs a new visual palette or font. Reusing a built-in key also picks up that key's existing CSS.

CSS tokensCopy Anchor Link

VisDelta reads its colours, type and line weights from CSS custom properties when it renders. Import visdelta/style.css once; it defines the default --vd-* tokens. Optional token themes are available as visdelta/themes/default.css, dark.css and paper.css.

Override tokens on a wrapper to restyle charts without changing any state:

.my-chart .vd-transition-root {
  --vd-color-surface: #ffffff;
  --vd-color-mark-default: #17171a;
  --vd-grid: #e8e8e4;
  --vd-axis-text: #5f5f66;
}

Without a colour declaration, marks use the style's neutral ink (--vd-color-mark-default) and draw no colour legend. Declared categorical palettes use --vd-series-1 to --vd-series-10 unless the state names a scheme or range. The defaults are VisDelta's logo blue, amber and coral, followed by seven more hues.

Dark modeCopy Anchor Link

The charts on this site follow the site theme by overriding tokens under a .dark ancestor. Because tokens are read at render time, refresh the chart after the theme changes:

themeToggle.addEventListener('click', () => {
  document.documentElement.classList.toggle('dark');
  change.resize(); // re-reads tokens, keeps the current progress
});