Viz

The base class every d3plus chart extends. It is not used directly: the configuration on this page applies to every chart, and each chart’s own page documents what it adds.

Viz owns the shared surface of every chart: loading and filtering data, groupBy hierarchies, color and size accessors, the title, legend, color scale, timeline, tooltip, zoom and table-view controls, and the render lifecycle. A chart definition plugs its layout into this pipeline, which is why the same config keys work on a Treemap and a LinePlot alike.

Linked charts

Hover a tile, search, or click a legend entry in either chart and the other follows. link takes a group name, or {group, by} to choose the value rows match on (default: each chart’s own id). Matching is by value, so a region tile in the Treemap lights up every country bar in that region. Set hover, active, highlight, or legend to false in the object form to stop mirroring that interaction.

const data = [
  {region: "Americas", country: "Brazil", revenue: 42},
  {region: "Americas", country: "Chile", revenue: 18},
  {region: "Americas", country: "Mexico", revenue: 27},
  {region: "Europe", country: "France", revenue: 35},
  {region: "Europe", country: "Germany", revenue: 39},
  {region: "Europe", country: "Spain", revenue: 21},
];

const config = {
  data,
  groupBy: ["region", "country"],
  sum: "revenue",
  title: "Revenue share",
  link: "viz-linked",
};

const data = [
  {region: "Americas", country: "Brazil", revenue: 42},
  {region: "Americas", country: "Chile", revenue: 18},
  {region: "Americas", country: "Mexico", revenue: 27},
  {region: "Europe", country: "France", revenue: 35},
  {region: "Europe", country: "Germany", revenue: 39},
  {region: "Europe", country: "Spain", revenue: 21},
];

const config = {
  data,
  groupBy: "country",
  x: "country",
  y: "revenue",
  color: "region",
  title: "Revenue by country",
  link: {group: "viz-linked", by: "country"},
};

Small multiples

facet splits a chart into a grid of equally sized panels, one per distinct value of a data key (or accessor). Every panel is the same chart drawn from its own rows, sharing one legend, title, timeline, and set of controls. Hover a bar to highlight its series in every panel, or click a legend entry to hide it everywhere. Panels share their x/y scales by default, so the axes are labeled only along the grid’s left and bottom edges.

Small multiples: line plot

The grid sizes itself: the column count is the one that draws the panels largest for the chart’s shape, so there is nothing to set. facetConfig.padding changes the space between panels. To pin the grid instead, set columns and/or rows (facetConfig: {columns: 5} puts every region in one row). The shared tooltip and crosshair follow the panel under the pointer.

const data = (() => {
  const regions = ["Africa", "Americas", "Asia", "Europe", "Oceania"];
  const products = ["Coffee", "Cocoa", "Tea"];
  const years = [2019, 2020, 2021, 2022, 2023];
  return regions.flatMap((region, r) =>
    products.flatMap((product, p) =>
      years.map((year, y) => ({
        region,
        product,
        year,
        exports: Math.round(
          (20 + ((r * 11 + p * 7 + y * 5) % 17) * 4) * (1 + r * 0.6),
        ),
      })),
    ),
  );
})();

const config = {
  data,
  groupBy: "product",
  x: "year",
  y: "exports",
  facet: "region",
  facetConfig: {padding: 12},
};

Small multiples: independent scales

With scales: "independent", each panel fits its own rows, which shows the shape of small regions at the cost of comparing heights across panels. Every panel then labels its own axes.

const data = (() => {
  const regions = ["Africa", "Americas", "Asia", "Europe", "Oceania"];
  const products = ["Coffee", "Cocoa", "Tea"];
  const years = [2019, 2020, 2021, 2022, 2023];
  return regions.flatMap((region, r) =>
    products.flatMap((product, p) =>
      years.map((year, y) => ({
        region,
        product,
        year,
        exports: Math.round(
          (20 + ((r * 11 + p * 7 + y * 5) % 17) * 4) * (1 + r * 0.6),
        ),
      })),
    ),
  );
})();

const config = {
  data,
  groupBy: "product",
  x: "year",
  y: "exports",
  stacked: true,
  facet: "region",
  facetConfig: {scales: "independent"},
};

Small multiples: donut

Any chart type can be faceted. sort orders the panels: "ascending" (the default), "descending", "data" (first appearance), a comparator, or an explicit list of values.

const data = (() => {
  const regions = ["Africa", "Americas", "Asia", "Europe", "Oceania"];
  const products = ["Coffee", "Cocoa", "Tea"];
  const years = [2019, 2020, 2021, 2022, 2023];
  return regions.flatMap((region, r) =>
    products.flatMap((product, p) =>
      years.map((year, y) => ({
        region,
        product,
        year,
        exports: Math.round(
          (20 + ((r * 11 + p * 7 + y * 5) % 17) * 4) * (1 + r * 0.6),
        ),
      })),
    ),
  );
})();

const config = {
  data: data.filter(d => d.year === 2023),
  groupBy: "product",
  value: "exports",
  title: "2023 export mix",
  facet: "region",
  facetConfig: {
    sort: ["Asia", "Europe", "Americas", "Africa", "Oceania"],
  },
};

Small multiples: treemap

One timeline drives every panel. title formats each panel’s title from its facet value and rows (or false hides them), and titleConfig styles them.

const data = (() => {
  const regions = ["Africa", "Americas", "Asia", "Europe", "Oceania"];
  const products = ["Coffee", "Cocoa", "Tea"];
  const years = [2019, 2020, 2021, 2022, 2023];
  return regions.flatMap((region, r) =>
    products.flatMap((product, p) =>
      years.map((year, y) => ({
        region,
        product,
        year,
        exports: Math.round(
          (20 + ((r * 11 + p * 7 + y * 5) % 17) * 4) * (1 + r * 0.6),
        ),
      })),
    ),
  );
})();

const config = {
  data,
  groupBy: "product",
  sum: "exports",
  time: "year",
  facet: "region",
  facetConfig: {
    title: (region, rows) =>
      `${region}: ${rows.reduce((s, d) => s + d.exports, 0)}`,
    titleConfig: {fontSize: 13, textAnchor: "start"},
  },
};

Small multiples: matrix

A colorScale is shared too: one scale, spanning the values every panel draws, colors all of them.

const data = (() => {
  const regions = ["Africa", "Americas", "Asia", "Europe", "Oceania"];
  const products = ["Coffee", "Cocoa", "Tea"];
  const years = [2019, 2020, 2021, 2022, 2023];
  return regions.flatMap((region, r) =>
    products.flatMap((product, p) =>
      years.map((year, y) => ({
        region,
        product,
        year,
        exports: Math.round(
          (20 + ((r * 11 + p * 7 + y * 5) % 17) * 4) * (1 + r * 0.6),
        ),
      })),
    ),
  );
})();

const config = {
  data,
  groupBy: ["product", "year"],
  row: "product",
  column: "year",
  colorScale: "exports",
  facet: "region",
};

Saving a chart

The download button in each chart’s top-left corner saves the chart as the reader sees it, title and legend included, without the controls or tooltip. With several formats it opens a menu; with one, it saves straight away. filename defaults to the title, background to the page color behind the chart, and saveControl: false removes the button.

const config = {
  data: [
    {region: "Americas", country: "Brazil", revenue: 42},
    {region: "Americas", country: "Chile", revenue: 18},
    {region: "Americas", country: "Mexico", revenue: 27},
    {region: "Europe", country: "France", revenue: 35},
    {region: "Europe", country: "Germany", revenue: 39},
    {region: "Europe", country: "Spain", revenue: 21},
  ],
  groupBy: "country",
  x: "country",
  y: "revenue",
  color: "region",
  title: "Revenue by country",
  // One format saves in one click. Other keys go to html-to-image.
  saveControlConfig: {
    filename: "revenue",
    formats: ["png"],
    background: "#f8f9fa",
    pixelRatio: 2,
  },
};

Polling for data

With a URL as data, dataPollingInterval re-fetches it every that many milliseconds and transitions to the new values, keeping hover, zoom, legend toggles, and the timeline selection. An unchanged response is not redrawn, a failed one keeps the last data and retries, and polling waits while the tab is hidden or the chart is scrolled out of view. This page answers the example’s URL itself, with a new reading on every request.

const config = {
  // This page answers this URL itself, with new readings on every request.
  data: "/demo/live-sales.json",
  groupBy: "region",
  x: "region",
  y: "sales",
  title: "Sales by region (refreshes every 2 seconds)",
  dataPollingInterval: 2000,
};

Styling with a class name

className adds classes to the element a chart draws on (its root <svg class="d3plus-viz">, or its <canvas> with the Canvas renderer) next to the fixed classes, so page CSS can style one chart: this page’s CSS gives .dark-chart a dark background and light text. It takes a space-separated string or an array, and a new value replaces the classes the last one added. Components drawn on their own (Axis, Legend, TextBox, …) take it on their <svg>, and tooltipConfig.className adds classes to a chart’s tooltips.

className

CSS classes added to the outermost element this chart or component draws into, next to its fixed d3plus classes, so page CSS can target it: a chart's root <svg class="d3plus-viz"> (its <canvas> with the Canvas renderer) and a standalone component's <svg>. Takes a space-separated string or an array. A new value replaces the classes the previous one added; unset adds none. Tooltips take their own tooltipConfig.className.

Reduced motion

By default (reducedMotion: "auto") a chart skips its transitions when the viewer’s OS asks for reduced motion, read from the (prefers-reduced-motion: reduce) media query at each draw. true always draws without motion and false always animates; duration keeps its value either way. Change a value in the code to compare: with true the bars jump to the new values, with false they animate.

const data = [
  {id: "North", year: 2021, value: 14},
  {id: "North", year: 2022, value: 18},
  {id: "North", year: 2023, value: 23},
  {id: "South", year: 2021, value: 9},
  {id: "South", year: 2022, value: 13},
  {id: "South", year: 2023, value: 11},
];

const config = {
  data,
  groupBy: "id",
  x: "year",
  y: "value",
  discrete: "x",
  title: "Revenue by region",
  duration: 800,
  reducedMotion: true,
};

With keyboardNav (on by default) each chart is a single Tab stop. The arrow keys move to the nearest mark in that direction, Home and End jump to the first and last, Enter or Space selects the focused mark as a click would (drilling down, or toggling a legend item), and Escape clears it. The focused mark shows its tooltip and hover highlight and a focus ring, and a live region announces it to screen readers. keyboardNavConfig styles the ring (stroke, strokeWidth, padding), and keyboardNav: false removes the Tab stop.

const data = [
  {id: "North", year: 2021, value: 14},
  {id: "North", year: 2022, value: 18},
  {id: "North", year: 2023, value: 23},
  {id: "South", year: 2021, value: 9},
  {id: "South", year: 2022, value: 13},
  {id: "South", year: 2023, value: 11},
];

const config = {
  data,
  groupBy: "id",
  x: "year",
  y: "value",
  discrete: "x",
  title: "Revenue by region",
  keyboardNavConfig: {stroke: "#005fcc", strokeWidth: 3},
};

Themes

theme sets every chrome color at once. "light" and "dark" paint the theme’s background behind the chart, so it reads the same on any page and in a saved image; the title, axes, gridlines, legend, timeline, tooltip, table view, and overlays all take the theme’s colors. An object sets your own tokens over the preset its base names. The default, "auto", paints no background and follows the page instead, redrawing when the page flips between light and dark. Colors set in other config (titleConfig.fontColor, tooltipConfig, the *Style options) still win.

const data = [
  {id: "North", year: 2021, value: 14},
  {id: "North", year: 2022, value: 18},
  {id: "North", year: 2023, value: 23},
  {id: "South", year: 2021, value: 9},
  {id: "South", year: 2022, value: 13},
  {id: "South", year: 2023, value: 11},
];

const config = {
  data,
  groupBy: "id",
  x: "year",
  y: "value",
  discrete: "x",
  title: "Revenue by region",
  // "auto" (the default), "light", "dark", or your own tokens on a preset:
  // {base: "dark", background: "#14213d", accent: "#fca311"}
  theme: "dark",
};

Configuration

import {Viz} from "@d3plus/core";

Filter 24 config keys

activefalse | function

The active callback function for highlighting shapes.

classNamestring | array.<string> | undefined

colorDefaultscolordefaultsconfig

Overrides the default colors used when assigning fills from data and choosing legible text colors: dark and light (the text colors picked for contrast against a background), missing (null/undefined values), on/off (true/false values), sequential (the anchor hue for magnitude ramps), and scale (the categorical palette, given as a d3 ordinal scale or an array of colors). Keys are merged into the current defaults, and a Viz passes its overrides down to the shapes and components it draws.

configd3plusconfig

Methods that correspond to the key/value pairs and returns this class.

datastring | array.<datapoint> | object

The primary data array used to draw the visualization. The value passed should be an Array of objects or a String representing a filepath or URL to be loaded. The following filetypes are supported: csv, tsv, txt, and json.

If your data URL needs specific headers to be set, an Object with a "url" and "headers" (or any other fetch request option) may also be passed. An Object with any other key is a data row, not a request.

Additionally, a custom formatting function can be passed as a second argument to this method. This custom function will be passed the data that has been loaded, as long as there are no errors. This function should return the final array of obejcts to be used as the primary data array. For example, some JSON APIs return the headers split from the data values to save bandwidth. These would need be joined using a custom formatter.

If you would like to specify certain configuration options based on the yet-to-be-loaded data, you can also return a full config object from the data formatter (including the new data array as a key in the object).

To re-fetch a URL on an interval and redraw when its data changes, set dataPollingInterval; each poll runs the same formatter.

Defaults to an empty array ([]).

Splits the chart into small multiples: a grid of equally sized panels, one per distinct value of this data key or accessor, each drawing the chart for that value's rows. The panels share one legend, color scale, title, and timeline, color each series the same way, and hover, tooltips, and legend clicks apply across all of them. Pass false to draw a single chart. See facetConfig for the grid's layout and shared scales.

facetConfigfacetconfig

Configuration for small multiples (see facet), merged into the current config: - columns / rows: the grid's shape. Chosen by default to make the panels as large as the chart's shape allows. - padding: the space between panels, in pixels (default 20). - sort: panel order — "ascending" (default), "descending", "data" (first appearance), a comparator over facet values, or an Array of values. - scales: "shared" (default) gives every panel of a chart with axes the same x/y domains; "independent" fits each panel to its own rows. Funnel defaults to "independent" (each panel sized to its own widest stage); "shared" sizes every panel against the widest stage across all panels. PolarArea and RadialBar default to "independent" (each panel's rings and ticks fit its own values); "shared" gives every panel the same value domain. - axes: with shared scales, "outer" (default) labels the axes only along the grid's left and bottom edges; "all" labels every panel. An object sets each axis on its own, as in {x: "all", y: "outer"}: every panel labels its x axis, only the left column labels its y axis, and the panels' plot areas line up. BumpChart defaults to "all", and Marimekko labels its categories on every panel and its 0–100% share axis only along the outer edge, even with independent scales. - title: a (value, data) => string function for each panel's title, or false to hide panel titles. - titleConfig: TextBox config for the panel titles (fontSize, fontWeight, fontColor, textAnchor, padding, …).

fontFamilystring | array.<string>

The font family used throughout the visualization.

groupBystring | function | array.<string | function>

Defines the mapping between data and shape. The value can be a String matching a key in each data point (default is "id"), or an accessor Function that returns a unique value for each data point. Additionally, an Array of these values may be provided if the visualization supports nested hierarchies.

highlightfalse | function

Persistently emphasizes the data points matching the given predicate: the matching marks keep their color while every other mark is de-emphasized to a neutral gray (the "emphasis" form — highlight one series, gray the rest). Unlike hover/active (transient, opacity-based), highlight is a standing state that survives pointer movement. Pass false to clear it.

hoverfalse | function

The hover callback function for highlighting shapes on mouseover.

localestring | object

The locale used for all text and number formatting. Supports the locales defined in d3plus-format. The locale can be a complex Object, a locale code (like "en-US"), or a 2-digit language code (like "en"). If a 2-digit code is provided, the "findLocale" function is used to identify the most approximate locale.

onstring

Event listener for the specified event typenames. Mirrors the core d3-selection behavior.

parentunknown

Parent config used by the wrapper.

renderfunction

Draws the visualization given the specified configuration.

rendererboolean | "svg" | "canvas"

Selects which @d3plus/render backend paints the visible output. "svg" = SvgRenderer (default), "canvas" = CanvasRenderer. Boolean arguments both normalize to "svg".

selectstring | htmlelement

The SVG container element as a d3 selector or DOM element. Defaults to undefined.

shapeConfigd3plusconfig

Configuration object with key/value pairs applied as method calls on each shape.

thresholdnumber | function

The threshold value for bucketing small data points together, as a share of the total. On a stacked Plot, the series whose summed value across every position is under that share of the whole chart's total merge into one series, stacked on top. A bucket needs at least two items, and its tooltips list them. Off (0) by default on Plot charts.

thresholdKeystring | function

Accessor for the value used in the threshold algorithm. A stacked Plot defaults to its stacked value.

timestring | false | function

Accessor function or string key for the time dimension of each data point.

timelineDefaultstring | date | array.<string | date>

The starting time or range for the timeline. Can be a single Date/String, or an Array of 2 values representing the min and max.

totalstring | boolean | function

Accessor function or string key for the total value displayed in the visualization.

translatefunction

Defines how informational text strings should be displayed. By default, this function will try to find the string in question (which is the first argument provided to this function) inside of an internally managed translation Object. If you'd like to override to use custom text, simply pass this method your own custom formatting function.

Viz