Configuration

Every D3plus visualization is configured the same way: each setting is a method on the chart, and that same name is also a key in the config object. You can mix and match the two styles.

The config object vs. method chaining

In vanilla JS, chain setters and finish with .render():

new d3plus.Treemap()
  .data([{id: "alpha", value: 29}, {id: "beta", value: 10}])
  .groupBy("id")
  .sum("value")
  .render();

…or pass everything at once with .config():

new d3plus.Treemap()
  .config({
    data: [{id: "alpha", value: 29}, {id: "beta", value: 10}],
    groupBy: "id",
    sum: "value"
  })
  .render();

In React, you always pass the config object:

<Treemap config={{
  data: [{id: "alpha", value: 29}, {id: "beta", value: 10}],
  groupBy: "id",
  sum: "value"
}} />

Each control in an example’s Controls panel corresponds one-to-one with a config key, and every chart’s page ends with its full configuration reference, so those are the fastest ways to discover what a chart accepts.

Accessors: values vs. functions

Most config keys accept either a constant, a property name (string), or an accessor function that receives the datum and its index:

.x("year")                          // read the "year" property
.x(d => new Date(d.year, 0, 1))     // derive a value per datum
.shapeConfig({fill: "#cc0000"})     // a constant for every shape
.shapeConfig({fill: d => d.color})  // per-datum

The RESET token

Pass the exported RESET token to restore any property to its built-in default (useful for clearing a value you set earlier):

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

chart.color(RESET).render();

Unknown property warnings

If a chart receives a config key it doesn’t support, usually a typo, it logs a console warning instead of silently ignoring it. This covers keys passed to .config() (including the React config prop), keys inside shapeConfig, and nested configs like xConfig or legendConfig:

new d3plus.BarChart().config({
  colr: "id",
  shapeConfig: {fil: "red", Bar: {strok: "blue"}}
});
// BarChart.config() received unknown property "colr".
// BarChart.shapeConfig() received unknown property "fil".
// BarChart.shapeConfig() received unknown property "Bar.strok".

A shapeConfig key is accepted if any shape type supports it, because one shapeConfig applies to every shape. A key nested under a shape name (like Bar: {...}) must exist on that shape. Each message is logged only once, so re-renders don’t repeat it.

To turn the warnings off for every chart on the page, call configWarnings once before creating your charts:

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

configWarnings(false);
configWarnings(); // → false

With a script tag, use d3plus.configWarnings(false).

Shared defaults with D3plusContext (React)

Wrap your app in D3plusContext.Provider to set defaults for every visualization. Per-component config props override globals key-by-key via a deep merge:

import {D3plusContext} from "@d3plus/react";

const globalConfig = {
  fontFamily: "Inter",
  timeline: false
};

<D3plusContext.Provider value={globalConfig}>
  <App />
</D3plusContext.Provider>

Re-rendering in React

The wrapper re-renders when the config prop changes (functions are compared by source). To force a redraw on every render cycle — e.g. when an external value the chart reads can’t be expressed in config — use the top-level forceUpdate prop:

<Treemap forceUpdate config={config} />

Migrating from v3? forceUpdate moved out of config and is now a top-level prop. See Guides → Migration.