WordCloud
Draws one word per row, its font size set by its value (size, read from
value by default). The words are placed largest first, each walking a
spiral out from the middle of the chart until it lands clear of the words
before it. Collisions are tested against each word’s actual glyphs, not its
box, so small words nest in the gaps of large ones. The same data always
gives the same layout. When the words don’t all fit, every font size shrinks
together until they do. Hover a word to see its value and its share of every
word drawn, and scroll or use the zoom controls to read the small ones.
Basic example
Section titled “Basic example”Each word’s text is its groupBy id (or its label), and rows with the same
id add up. Font sizes run from fontMin to fontMax, by the square root of
the value by default (fontScale), so each word’s ink area grows roughly in
step with its count.
Accessor function or data key for each word's value, which sets its font size. Rows with the same id add up. Defaults to "value".
The smallest font size, in pixels, given to the word with the smallest value.
The largest font size, in pixels, given to the word with the largest value. When the words don't all fit, every size shrinks together until they do.
How values map onto font sizes between fontMin and fontMax: "sqrt" (default) so each word's ink area grows about in step with its value, "linear" for its height, or "log" for values spanning orders of magnitude.
The words' font weight: a number or keyword, or an accessor (d, i) => weight per word.
The clearance, in pixels, kept around each word's glyphs.
The path each word walks out from the middle while looking for room: "archimedean" (default) packs the words into a rounded cloud, "rectangular" into a boxier one.
Colored by group
Section titled “Colored by group”With two groupBy levels, the outer one colors the words and fills the
legend. Hover a legend entry to highlight its words, or click it to hide
them.
Defines the main color to be used for each data point in a visualization. Can be either an accessor function or a string key to reference in each data point. If a color value is returned, it will be used as is. If a string is returned, a unique color will be assigned based on the string.
When the color is a category that isn't one of the groupBy levels (for example, points grouped by "country" and colored by "region"), the legend shows one entry per category, labelled by the category. Clicking, shift+clicking, or hovering an entry hides, solos, or highlights every item in that category.
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.
["group", "word"]Rotated words
Section titled “Rotated words”rotate turns the words: a number turns every word, an array of angles
gives each word one of them (picked from its name, so it keeps its angle
across redraws), and a function (d, i) => degrees sets each word’s own.
By default every word is horizontal.
The path each word walks out from the middle while looking for room: "archimedean" (default) packs the words into a rounded cloud, "rectangular" into a boxier one.
Color scale
Section titled “Color scale”colorScale colors each word by a second measure, here the share of its
mentions that come from positive reviews.
// `positive` is the share of each word's mentions in positive reviews.
const words = [
{word: "data", count: 2369, positive: 0.12},
{word: "chart", count: 1312, positive: 0.69},
{word: "color", count: 1010, positive: 0.47},
{word: "visual", count: 685, positive: 0.48},
{word: "scale", count: 568, positive: 0.52},
{word: "interactive", count: 494, positive: 0.69},
{word: "draw", count: 380, positive: 0.67},
{word: "label", count: 374, positive: 0.79},
{word: "map", count: 348, positive: 0.46},
{word: "story", count: 332, positive: 0.05},
{word: "compare", count: 247, positive: 0.99},
{word: "legend", count: 244, positive: 0.15},
{word: "sparse", count: 212, positive: 0.99},
{word: "category", count: 247, positive: 0.29},
{word: "quantitative", count: 225, positive: 0.77},
{word: "sum", count: 174, positive: 0.25},
{word: "complex", count: 218, positive: 0.87},
{word: "animation", count: 206, positive: 0.45},
{word: "line", count: 180, positive: 0.89},
{word: "plot", count: 171, positive: 0.87},
{word: "tell", count: 142, positive: 0.41},
{word: "simple", count: 130, positive: 0.89},
{word: "theme", count: 147, positive: 0.15},
{word: "cluster", count: 122, positive: 0.23},
{word: "pixel", count: 123, positive: 0.49},
{word: "static", count: 121, positive: 0.26},
{word: "accurate", count: 109, positive: 0.42},
{word: "timeline", count: 121, positive: 0.57},
{word: "font", count: 117, positive: 0.62},
{word: "bold", count: 127, positive: 0.78},
{word: "value", count: 113, positive: 0.8},
{word: "accessible", count: 114, positive: 0.4},
{word: "export", count: 106, positive: 0.63},
{word: "point", count: 108, positive: 0.07},
{word: "audience", count: 100, positive: 0.16},
{word: "axis", count: 92, positive: 0.05},
{word: "subtitle", count: 110, positive: 0.15},
{word: "readable", count: 107, positive: 0.37},
{word: "embed", count: 101, positive: 0.87},
{word: "tree", count: 95, positive: 0.15},
{word: "dashboard", count: 83, positive: 0.35},
{word: "threshold", count: 79, positive: 0.12},
{word: "minimal", count: 79, positive: 0.49},
{word: "insight", count: 72, positive: 0.1},
{word: "honest", count: 87, positive: 0.27},
{word: "aggregate", count: 77, positive: 0.16},
{word: "dynamic", count: 86, positive: 0.95},
{word: "render", count: 74, positive: 0.15},
{word: "zoom", count: 85, positive: 0.03},
{word: "highlight", count: 81, positive: 0.98},
{word: "tick", count: 62, positive: 0.69},
{word: "link", count: 66, positive: 0.37},
{word: "categorical", count: 79, positive: 0.77},
{word: "sample", count: 69, positive: 0.78},
{word: "transition", count: 78, positive: 0.22},
{word: "domain", count: 65, positive: 0.99},
{word: "sort", count: 58, positive: 0.81},
{word: "nest", count: 68, positive: 0.74},
{word: "explore", count: 69, positive: 0.03},
{word: "logarithmic", count: 59, positive: 0.28},
];
const config = {
colorScale: "positive",
colorScaleConfig: {
axisConfig: {tickFormat: d => `${Math.round(d * 100)}%`},
},
data: words,
groupBy: "word",
size: "count",
};
Threshold
Section titled “Threshold”threshold merges the words under that share of the total into one word,
named by thresholdName and drawn like any other, sized by their summed
value. Its tooltip lists the words it holds. By default, as on Treemap, the
words under 0.01% of the total merge; set threshold: 0 to draw every
word.
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.
Label for the threshold group, or a (datum, index) accessor.
Small multiples
Section titled “Small multiples”facet draws a cloud per part of speech. Each panel sizes its own words, so
compare words within a panel rather than across panels.
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.
Configuration
import {WordCloud} from "@d3plus/core";
Extends Viz.
activefalse|functionThe active callback function for highlighting shapes.
aggsobjectCustom aggregation functions keyed by data property.
appenddatapoint|array.<datapoint>Adds rows to the chart's data and redraws it: lines extend, the axes slide to take in the new rows, and every mark already drawn tweens to its new place rather than redrawing. Appends that land before the next animation frame share one redraw.
options.windowdrops the oldest rows: a number keeps the latest that many rows, and a time span ("5 minutes","90s","300000ms","1.5 hours"; units frommstoweeks) keeps the rows within that span of the latest time, read fromtime, or else from the discrete axis (a LinePlot'sx).Unlike setting
data, appending keeps the series a viewer hid or soloed in the legend and the period they picked on the timeline. Rows are added to the data the chart holds, after anydataFormat; a later poll (seedataPollingInterval) replaces them.ariaHiddenbooleanDefaulttrueHides the SVG from assistive technology when true (
aria-hidden).attributionstring|booleanDefaultfalseSets text to be shown positioned absolute on top of the visualization in the bottom-right corner. This is most often used in Geomaps to display the copyright of map tiles. The text is rendered as HTML, so any valid HTML string will render as expected (eg. anchor links work).
attributionIconstring|functionOverrides the "ⓘ" icon a long attribution collapses to (see
attribution), which otherwise renders as an inline SVG. Accepts an HTML string — used as the toggle button's content — or a mount function,(el: HTMLElement) => void | (() => void), called once with the button's reserved icon slot so a live component (a React tree viacreateRoot(el).render(...), or anything else imperative) can be mounted into it. A returned cleanup function runs right before that slot is discarded, which happens whenever the credit's markup regenerates (its text or theme changes), not just once per chart.attributionStylerecordCSS key/value pairs used to style the attribution text.
backControlClassNamestringAn additional CSS class name (or space-separated list of class names) applied to the back button, alongside its fixed
back-controlclass. Setting this automatically disables d3plus's built-in inlinebackControlStyledefault (as long as you haven't already customized it yourself), so a host page's own button styling — Tailwind, Bootstrap, a design system — applies through the cascade with no other configuration needed.backControlStylerecord|falseAn object containing CSS key/value pairs that is used to style the back button. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.backControlClassName(...)is set, unless you've explicitly customized this yourself.cachebooleanDefaulttrueWhether the chart uses the data cache that every chart on the page shares for the files fetched by
data,links,nodes,topojson, andfitObject, so charts loading the same URL share one request and loading it again, or changing a formatter, needs none. The cache uses up to about 50 MB of memory, dropping the least recently used files first. Defaults totrue;falsefetches on every load.clearDataCache()from@d3plus/dataempties the cache.classNamestring|array.<string>|undefinedCSS 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 owntooltipConfig.className.colorstring|false|functionDefines the main color to be used for each data point in a visualization. Can be either an accessor function or a string key to reference in each data point. If a color value is returned, it will be used as is. If a string is returned, a unique color will be assigned based on the string.
When the color is a category that isn't one of the
groupBylevels (for example, points grouped by"country"and colored by"region"), the legend shows one entry per category, labelled by the category. Clicking, shift+clicking, or hovering an entry hides, solos, or highlights every item in that category.colorDefaultscolordefaultsconfigOverrides the default colors used when assigning fills from data and choosing legible text colors:
darkandlight(the text colors picked for contrast against a background),missing(null/undefined values),on/off(true/falsevalues),sequential(the anchor hue for magnitude ramps), andscale(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.colorOrdinalbooleanDefaultfalseTreat a discrete color field as ordered: color it with a single-hue light→dark ramp instead of nominal categorical hues.
colorScalestring|[colorscalefield, colorscalefield]|false|functionDefines the value to be used for a color scale. Can be either an accessor function or a string key to reference in each data point. Two of them (
["a", "b"]) make a bivariate scale: each variable is split into quantile bins, the pair of bins picks a color from a grid, and the key is that grid turned into a diamond (seecolorScaleConfig.bivariateBuckets,bivariateColors, andbivariateLabels). A row missing either value gets no colorScale color.colorScaleConfigobjectA pass-through to the config method of ColorScale.
colorScaleMaxSizenumberDefault600The maximum pixel size for drawing the color scale: width for horizontal scales and height for vertical scales.
colorScalePaddingboolean|functionTells the colorScale whether or not to use the internal padding defined by the visualization in it's positioning. For example, d3plus-plot will add padding on the left so that the colorScale appears centered above the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
colorScalePositionfalse|panelposition|functionDefines which side of the visualization to anchor the color scale. Acceptable values are
"auto"(the default),"top","bottom","left","right", andfalse."auto"lets the chart choose: inside the chart when it fits there (seelegendInset), otherwise the right side of charts more than 1.5 times as wide as they are tall and the bottom of all others. Any other side keeps the color scale there. Afalsevalue will cause the color scale to not be displayed, but will still color shapes based on the scale.configd3plusconfigMethods that correspond to the key/value pairs and returns this class.
datastring|array.<datapoint>|objectThe 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, andjson.If your data URL needs specific headers to be set, an Object with a "url" and "headers" (or any other
fetchrequest option) may also be passed. An Object with any other key is a data row, not a request.To transform the data before it is drawn (for example, a JSON API that returns its headers split from its values), set
dataFormat. Passing a formatter as a second argument to this method setsdataFormat; calling it with only data keeps the currentdataFormat.To re-fetch a URL on an interval and redraw when its data changes, set
dataPollingInterval; each poll runsdataFormat.Defaults to an empty array (
[]).dataCutoffnumberDefault500Maximum number of data points to render before downsampling.
dataFormatfunctionTransforms
databefore it is drawn: receives the loaded file (or the Array passed asdata) and returns the rows to draw, or a config object holding them asdata(its other keys are applied to the chart). Also set bydata(url, format).dataPollingIntervalnumber|falseDefaultfalseWhen
datacomes from a URL, re-fetches it every this many milliseconds and redraws when it changes, keeping hover, zoom, and legend state. Polling pauses while the tab (or, withdetectVisible, the chart) is hidden, and a failed request keeps the last data. Onlydatais polled. Defaults tofalse(load once).depthnumberActive depth level for nested groupings.
detectResizebooleanDefaulttrueIf the width and/or height of a Viz is not user-defined, it is determined by the size of it's parent element. When this method is set to
true, the Viz will listen for thewindow.onresizeevent and adjust it's dimensions accordingly.detectResizeDelaynumberDefault400When resizing the browser window, this is the millisecond delay to trigger the resize event.
detectVisiblebooleanDefaulttrueToggles whether or not the Viz should try to detect if it visible in the current viewport. When this method is set to
true, the Viz will only be rendered when it has entered the viewport either through scrolling or if it's display or visibility is changed.detectVisibleIntervalnumberDefault1000The interval, in milliseconds, for checking if the visualization is visible on the page. When
detectVisibledefers a render until the visualization scrolls into view, this is also how long it must stay in view before it renders, so visualizations scrolled past quickly are never drawn.detectVisibleUnloadbooleanDefaulttrueWith
detectVisibleon, releases the chart's DOM and scene while it is scrolled out of view and redraws it when it returns, keeping pages with many charts light. Data and config are kept; zoom and selection are not, so setfalseto keep them. Defaults totrue.discrete"x"|"y"|"radius"|"angle"Sets orientation of main category axis. Left unset on a Plot (Scatter, BubbleChart, …), the axis whose values include text is the category axis (when both do, the one with fewer distinct values,
xon a tie); numbers stored as text stay continuous. With no text on either axis, a Plot drawing a Bar, Area, or Box stands it onx.durationnumberDefault600Default duration of transitions, in milliseconds.
facetstring|false|functionSplits 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
falseto draw a single chart. SeefacetConfigfor the grid's layout and shared scales.facetConfigfacetconfigConfiguration 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 (default20). -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, RadialBar, RadialLine and RadialArea 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) => stringfunction for each panel's title, orfalseto hide panel titles. -titleConfig: TextBox config for the panel titles (fontSize,fontWeight,fontColor,textAnchor,padding, …). -layout: places each panel on a map-shaped grid:"us-states","eu-countries","world-regions", or{[value]: [row, column]}. Empty cells stay empty, values the grid lacks are left out with a warning, and a named grid titles panels with short codes, showing the full name on hover and heading its marks' tooltips with it.filterfalse|functionPredicate filtering which data points are included, or false to disable.
fontFamilystring|array.<string>The font family used throughout the visualization.
fontMaxnumberDefault60The largest font size, in pixels, given to the word with the largest value. When the words don't all fit, every size shrinks together until they do.
fontMinnumberDefault10The smallest font size, in pixels, given to the word with the smallest value.
fontScale"sqrt"|"linear"|"log"DefaultsqrtHow values map onto font sizes between
fontMinandfontMax:"sqrt"(default) so each word's ink area grows about in step with its value,"linear"for its height, or"log"for values spanning orders of magnitude.fontWeightnumber|string|functionDefault600The words' font weight: a number or keyword, or an accessor
(d, i) => weightper word.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.
heightnumberOverall height of the visualization in pixels.
Defines the color used for legend shapes when the corresponding grouping is hidden from display (by clicking on the legend).
Defines the opacity used for legend labels when the corresponding grouping is hidden from display (by clicking on the legend).
highlightfalse|functionPersistently 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),highlightis a standing state that survives pointer movement. Passfalseto clear it.hoverfalse|functionThe hover callback function for highlighting shapes on mouseover.
hoverDistancenumberDefault20How close (px) the pointer must come to a point mark (scatter and bubble points, Network nodes, Geomap points, Radar dots) to hover it, so small points are easy to reach. Defaults to
20;0turns it off.Lets keyboard users move between the chart's marks: the chart is one Tab stop, the arrow keys move to the nearest mark in that direction, Home and End jump to the ends, Enter or Space click the focused mark, and Escape clears it. Defaults to
true;falseremoves the Tab stop.Styles the focus ring around the mark keyboard navigation has focused (see
KeyboardNavConfig).labelstring|false|accessorfn|array.<string>Accessor function, or a constant string applied to every data point's label (unlike
value/nodeId/etc., a string here is not treated as a per-datum object key — pass a function for that).labelPosition"auto"|"along"|"inside"|"outside"|functionWhere each shape's label goes:
"auto","along","inside", or"outside", or a(d, i) => stringaccessor."auto"picks whichever fits best per shape, and a label with no room is left out.- Rings (Pie, Donut, Sunburst, Chord, RadialBar) and polar charts (Radar, PolarArea, RadialMatrix):
"along"curves the name along its arc."inside"keeps it straight; on a Pie or Donut,"outside"moves it beside the ring with a leader line. - Bars: inside or outside the bar."auto"goes outside when the bar is short. Stacked bars always label inside. - Circles (Plot points, Network nodes, Geomap points): inside the circle, or beside it when it doesn't fit ("outside"always beside)."auto"also moves it beside when a circle drawn over its own covers it, and keeps it inside when no side has room. - Stacked areas:"auto"and"along"run each name along its band;"inside"puts it in the band's largest box.When every stacked area or RadialBar track is named along its shape, the default legend hides. Defaults to
"auto".labelSlidebooleanDefaulttrueCircles (Plot points, Network nodes, Geomap points): whether a label that fits neither inside its circle nor centered on a side of it slides along a side before it hides, clear of the other circles and labels (and, on a Network, crossing as few links as it can). It may also move a neighbor's label aside to make room.
falsekeeps each label centered on a side, or hides it. Defaults totrue.legendboolean|functionDefaultrowLegendWhether to display the legend. By default it shows when it has more than one entry and each entry stands for a single group, or when entries are colored by a category that isn't a
groupBylevel. It hides when the chart's own labels already name every entry (seelabelPosition), or when every Circle, Rect, and Bar of a Plot shows its whole label as its legend entry would, and stays while a series is hidden or soloed.falsehides it,truealways shows it, and a(config, data) => booleanfunction decides.legendConfigobjectConfiguration object passed to the legend's config method.
legendFilterInvertboolean|functionDefines the click functionality of categorical legend squares. When set to false, clicking will hide that category and shift+clicking will solo that category. When set to true, clicking will solo that category and shift+clicking will hide that category. The Back button undoes each click (see
legendHistory).legendHistorybooleanDefaulttrueWhether legend clicks go on the chart's Back history, so Back undoes them along with drill-downs, in order. Defaults to
true;falseleaves them off, so Back only steps out of drill-downs.legendInsetboolean|functionDefaulttrueWhether the chart may draw a legend, size legend, or colorScale inside empty space around its marks (over a translucent box, see
legendInsetConfig) instead of in a margin. Only a legend whose position is"auto"can move inside. Defaults totrue; also accepts a function of the resolved config.legendInsetConfigobjectStyle of the box drawn behind a legend placed inside the chart (see
legendInset):fill(defaults to the chart's background color),fillOpacity(0.85),stroke(defaults to a faint contrasting line),strokeWidth(1),rx(corner radius, 4),margin(space between the box's edge and the legend, 6), andpadding(space kept between the box and the chart's marks and edges, 10).legendPaddingboolean|functionTells the legend whether or not to use the internal padding defined by the visualization in it's positioning. For example, d3plus-plot will add padding on the left so that the legend appears centered underneath the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
legendPositionfalse|panelposition|functionDefines which side of the visualization to anchor the legend. Expected values are
"auto"(the default),"top","bottom","left","right", andfalseto hide it."auto"lets the chart choose: inside the chart when it fits there (seelegendInset), otherwise the right side of charts more than 1.5 times as wide as they are tall and the bottom of all others. Any other side keeps the legend there.legendSortfunctionDefaultlegendLargestFirst(viz, wordSize(viz))Comparator that orders the legend's entries. By default the legend reads in the order the chart draws: Treemap, Pack, Pie, Donut, Icicle, and Sunburst list their largest entries first; a stacked chart lists its series in stacking order, from the baseline outward (so the default
stackOrder,"descending", lists the largest first); Waffle and Waterfall follow their own order, and Network and ArcDiagram clusters come largest first; every other chart is alphabetical by label. A threshold group always comes last, whatever the sort.legendTooltiptooltipconfigDefault{tbody: wordCloudTooltipRows(viz)}Configuration object for the legend tooltip.
linklinkoptionLinks this chart to every other chart with the same group name, so hovering,
active,highlight(including search), and legend hide/solo clicks in one are mirrored in the rest, and a value gets the same categorical color in every chart. Rows match across charts by the value ofby(a data key or accessor), which defaults to the chart's own id. A string is shorthand for{group}; sethover,active,highlight,legend, orcolortofalseto stop sharing that behavior.loadingHTMLstring|functionThe inner HTML of the status message displayed when loading AJAX requests and displaying errors. Must be a valid HTML string or a function that, when passed this Viz instance, returns a valid HTML string.
loadingMessagebooleanDefaulttrueToggles the visibility of the status message that is displayed when loading AJAX requests and displaying errors.
localestring|objectThe 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.
messageMaskstring|booleanDefaultrgba(0, 0, 0, 0.05)The color of the mask displayed underneath the status message when loading AJAX requests and displaying errors. Set to
falseto turn off the mask completely.messageStylerecordDefines the CSS style properties for the status message that is displayed when loading AJAX requests and displaying errors.
minimapbooleanDefaulttrueShows a small overview + draggable-viewport minimap in the chart's top-right corner (beneath the zoom controls, when they show) once the chart is zoomed in. On by default whenever
zoomis enabled.minimapClassNamestringAn additional CSS class name (or space-separated list of class names) applied to the minimap's outer box, viewport box, and zoom-level label, alongside their fixed
d3plus-minimap/d3plus-minimap-viewport/d3plus-minimap-labelclasses. Setting this automatically disables d3plus's built-in inlineminimapStyle/minimapViewportStyle/minimapViewportStyleActive/minimapLabelStyledefaults (as long as you haven't already customized them yourself), so a host page's own styling applies through the cascade with no other configuration needed.minimapLabelStylerecord|falseAn object containing CSS key/value pairs that is used to style the minimap's zoom-level text label (e.g. "2x"). Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.minimapClassName(...)is set, unless you've explicitly customized this yourself.minimapStylerecord|falseAn object containing CSS key/value pairs that is used to style the minimap's outer box (the full-scene overview). Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.minimapClassName(...)is set, unless you've explicitly customized this yourself.minimapViewportStylerecord|falseAn object containing CSS key/value pairs that is used to style the minimap's draggable viewport box in its resting state. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.minimapClassName(...)is set, unless you've explicitly customized this yourself.minimapViewportStyleActiverecord|falseAn object containing CSS key/value pairs that is used to style the minimap's draggable viewport box while it's being dragged. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.minimapClassName(...)is set, unless you've explicitly customized this yourself.noDataHTMLstring|functionThe inner HTML of the status message displayed when no data is supplied to the visualization. Must be a valid HTML string or a function that, when passed this Viz instance, returns a valid HTML string.
noDataMessagebooleanDefaulttrueToggles the visibility of the status message that is displayed when no data is supplied to the visualization.
onstringEvent listener for the specified event typenames. Mirrors the core d3-selection behavior.
parentunknownParent config used by the wrapper.
pointLabelConfigpointlabelconfigFits and styles circle labels (see
labelPosition):fontMinis the smallest font size a label may shrink to inside its circle before"auto"moves it beside the circle (default10, the size of the chart's smallest text, its total);fontSizeis the size of a label beside its circle (default11);paddingis the space between the circle's edge and that label (default3). The other TextBox keys (fontColor,fontFamily,fontWeight,fontOpacity, …) style the labels beside their circles, which default to the chart's text color. Merged into the current config.reducedMotion"auto"|booleanDefaultautoWhether the chart animates.
"auto"(default) follows the viewer's OS setting, read from the(prefers-reduced-motion: reduce)media query at each draw (server-side rendering counts as not reduced).truealways draws without motion: shapes, axes, legends, zooms, and fades jump straight to their final state.falsealways animates.durationkeeps the value you set either way.renderfunctionDraws the visualization given the specified configuration. An error thrown while the chart draws (by an accessor in its config, say) is logged with
console.error, and the chart keeps what it last painted.rendererboolean|"svg"|"canvas"Selects which @d3plus/render backend paints the visible output.
"svg"= SvgRenderer (default),"canvas"= CanvasRenderer. Boolean arguments both normalize to"svg".rotatenumber|number[]|functionDefault0The angle, in degrees clockwise, each word is drawn at: a number for every word, an array of angles (each word takes one, picked from a hash of its id, so it keeps its angle across redraws), or an accessor
(d, i) => degrees. Defaults to0, every word horizontal.saveControlbooleanDefaulttrueShows a top-left download button that saves the chart, as the reader sees it, as a PNG, SVG, or JPG file. On by default for every chart.
saveControlClassNamestringAn additional CSS class name (or space-separated list of class names) applied to the download button, alongside the fixed
save-control/save-toggleclasses. Setting this automatically disables d3plus's built-in inlinesaveControlStyle/saveControlStyleActive/saveControlStyleHoverdefaults (as long as you haven't already customized them yourself), so a host page's own button styling applies through the cascade with no other configuration needed.saveControlConfigsavecontrolconfigOptions for the download button: the saved file's
filename, theformatsit offers, thebackgroundpainted behind the chart, acallback, and html-to-image options for PNG and JPG files.saveControlMenuClassNamestringAn additional CSS class name (or space-separated list of class names) applied to the download menu, alongside its fixed
d3plus-save-menuclass (each item has the fixedsave-menu-itemclass). Setting this automatically disables d3plus's built-in inlinesaveControlMenuStyle/saveControlMenuItemStyle/saveControlMenuItemStyleHoverdefaults (as long as you haven't already customized them yourself), so a host page's own menu styling applies through the cascade. The menu's position and open/closed display stay inline.saveControlMenuItemStylerecord|falseAn object containing CSS key/value pairs that is used to style each item in the download menu. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.saveControlMenuClassName(...)is set, unless you've explicitly customized this yourself.saveControlMenuItemStyleHoverrecord|falseAn object containing CSS key/value pairs that is used to style the download menu item under the pointer or keyboard focus. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.saveControlMenuClassName(...)is set, unless you've explicitly customized this yourself.saveControlMenuStylerecord|falseAn object containing CSS key/value pairs that is used to style the download menu: its background, border, shadow, and spacing. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.saveControlMenuClassName(...)is set, unless you've explicitly customized this yourself.saveControlStylerecord|falseAn object containing CSS key/value pairs that is used to style the download button. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.saveControlClassName(...)is set, unless you've explicitly customized this yourself.saveControlStyleActiverecord|falseAn object containing CSS key/value pairs that is used to style the download button while its menu is open. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.saveControlClassName(...)is set, unless you've explicitly customized this yourself.saveControlStyleHoverrecord|falseDefaultfalseAn object containing CSS key/value pairs that is used to style the download button on hover. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.saveControlClassName(...)is set, unless you've explicitly customized this yourself.scrollContainerstring|htmlelement|windowIf using scroll or visibility detection, this method allow a custom override of the element to which the scroll detection function gets attached.
searchbooleanDefaulttrueShows a top-left search button that expands into an input; typing highlights shapes whose label matches. On by default for every chart.
searchAccessorfunctionResolves the string the search box matches its typed term against, for a given datum. Defaults to the mark's resolved on-screen label (
viz._drawLabel) — the same text the user reads on the chart. Override it to match against something else instead, e.g. a data field that isn't shown as the label.This is checked alongside, not instead of, every level of the datum's own groupBy hierarchy — searching a leaf's label also matches its ancestor group's cell/legend entry, and vice versa, regardless of this accessor's override.
searchControlClassNamestringAn additional CSS class name (or space-separated list of class names) applied to the search toggle button and input, alongside their fixed
search-controlclasses. Setting this automatically disables d3plus's built-in inlinesearchControlStyle/searchControlStyleActive/searchControlStyleHoverdefaults (as long as you haven't already customized them yourself), so a host page's own button styling — Tailwind, Bootstrap, a design system — applies through the cascade with no other configuration needed.searchControlStylerecord|falseAn object containing CSS key/value pairs that is used to style the search toggle button. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.searchControlClassName(...)is set, unless you've explicitly customized this yourself.searchControlStyleActiverecord|falseAn object containing CSS key/value pairs that is used to style the search toggle button while open. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.searchControlClassName(...)is set, unless you've explicitly customized this yourself.searchControlStyleHoverrecord|falseDefaultfalseAn object containing CSS key/value pairs that is used to style the search toggle button on hover. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.searchControlClassName(...)is set, unless you've explicitly customized this yourself.selectstring|htmlelementThe SVG container element as a d3 selector or DOM element. Defaults to
undefined.selectMode"box"|"lasso"|falseDefaultfalseThe box and lasso selection tool a chart starts with:
"box"or"lasso", orfalse(the default) to start out panning. Whatever it starts with, the zoom controls' Box Select and Lasso Select buttons switch between the tools, or back to panning when the one on is pressed again (the brush-zoom button turns selection off too), and changingselectModelater resets the tool.While a tool is on, a drag over the chart draws a box (or a freehand lasso) instead of panning, and releasing it selects the marks inside, which stay lit while the rest dim (as
activeOpacitydims them), the legend included. A bar or other rectangle is inside when any part of it is, every other mark (a point, a point of a line or area) when its center is, and a line or area stays lit while any of its points is selected. Shift + drag adds to the selection, a click on a mark selects it (Shift + click toggles it, and the chart's own click action, such as drilling down, waits until no select tool is on), and Escape or a click on no mark clears it. With small multiples, a drag selects within the panel it starts in. A wheel or pinch still zooms. Each selection fires the chart'sselectevent with the selected rows (viz.on("select", rows => …)), andselectionreads or sets the selection from code.selectStylerecordSVG attributes for the box or lasso a selection drag draws, such as
fill,fill-opacity,stroke, andstroke-dasharray.selectionselectionvalueThe rows a box or lasso selection holds (see
selectMode), read off the chart as last drawn. Set it from code with an Array of rows (the same objects, or rows with the same values), a predicate over rows, orfalseto clear it: the selected marks stay lit while the rest dim, with or without a select tool on. A selection set here fires noselectevent, and it holds across redraws and data changes for as long as its rows (or the predicate's) are still drawn.shapeConfigd3plusconfigConfiguration object with key/value pairs applied as method calls on each shape. On a Plot, a shape's
width,height,r,x,y, oridreads a string as the data field to read from each row, and any other value as a constant, as the shape's own setters do.sizestring|functionDefaultdefaultSizeAccessor function or data key for each word's value, which sets its font size. Rows with the same id add up. Defaults to
"value".sizeLegendboolean|functionWhether to display the size legend: a nested-circle key, in the chart's bottom-right corner, for charts that size their marks with a
sizeaccessor (bubble plots, Geomap points viapointSizeand Dorling or Demers cartograms viacartogramSize, Network, Rings). By default it shows whenever marks are sized by more than one value, unless it would take up more than a third of the chart's width or height. Passtrueto always show it,falseto hide it, or a function that receives the resolved chart config, the radius scale, and the legend's measured{width, height, availableWidth, availableHeight}, and returns a boolean.sizeLegendConfigsizelegendconfigConfiguration object passed to the size legend's config method:
values(an array of values to draw, or how many to pick),tickFormat,title(defaults to thesizekey whensizeis set to a string),shapeConfig,lineConfig,labelConfig,titleConfig,padding,lineLength, andlabelPadding.sizeLegendPosition"right"|"bottom"DefaultrightWhich margin the size legend claims in the chart's bottom-right corner.
"right"(the default) widens the right margin, so the chart keeps its full height and the legend sits at the bottom of the right column, below any right-side legend or colorScale."bottom"deepens the bottom margin instead, so the chart keeps its full width and any bottom legend or colorScale narrows to sit beside it.spiral"archimedean"|"rectangular"DefaultarchimedeanThe path each word walks out from the middle while looking for room:
"archimedean"(default) packs the words into a rounded cloud,"rectangular"into a boxier one.subtitlestring|functionAccessor function or string for the visualization's subtitle.
subtitleConfigrecordConfiguration object for the subtitle.
subtitlePaddingboolean|functionTells the subtitle whether or not to use the internal padding defined by the visualization in it's positioning. For example, d3plus-plot will add padding on the left so that the subtitle appears centered above the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
svgDescstringAccessible description applied to the root SVG (
<desc>).svgTitlestringAccessible title applied to the root SVG (
<title>).tableViewbooleanDefaulttrueEnables the top-left table-view toggle button, which swaps the chart for a static, scrollable
<table>of its data. On by default for every chart.tableViewClassNamestringAn additional CSS class name (or space-separated list of class names) applied to the
<table>element the table-view toggle renders, alongside the fixedd3plus-table-view-tableclass. Lets a host page style the data table with its own table styling (Tailwind, Bootstrap, a design system) via descendant selectors.tableViewControlClassNamestringAn additional CSS class name (or space-separated list of class names) applied to the table-view toggle button, alongside the fixed
table-view-control/table-view-toggleclasses. Setting this automatically disables d3plus's built-in inlinetableViewControlStyle/tableViewControlStyleActive/tableViewControlStyleHoverdefaults (as long as you haven't already customized them yourself), so a host page's own button styling applies through the cascade with no other configuration needed.tableViewControlStylerecord|falseAn object containing CSS key/value pairs that is used to style the table-view toggle button. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.tableViewControlClassName(...)is set, unless you've explicitly customized this yourself.tableViewControlStyleActiverecord|falseAn object containing CSS key/value pairs that is used to style the table-view toggle button while it is active (showing the data table). Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.tableViewControlClassName(...)is set, unless you've explicitly customized this yourself.tableViewControlStyleHoverrecord|falseDefaultfalseAn object containing CSS key/value pairs that is used to style the table-view toggle button on hover. Passing
falsewill remove all default styling. Automatically skipped (as iffalse) once.tableViewControlClassName(...)is set, unless you've explicitly customized this yourself.tableViewDownloadbooleanDefaulttrueWhether the data table shows a "download CSV" button, exporting its full (sorted, unpaginated) rows. On by default.
tableViewPageSizenumber|falseDefault50The number of data-table rows shown per page while in table view. Set to
false(or any non-positive number) to disable pagination and show every row on one page.tableViewSortbooleanDefaulttrueWhether the data table's column headers are clickable to sort (toggling asc/desc). On by default.
themethemesettingDefaultautoThe chart's colors.
"auto"(the default) paints no background and follows the page, light or dark."light"and"dark"paint the theme's background and take every chrome color from it. An object overrides tokens on top of itsbasepreset, e.g.{base: "dark", background: "#123", accent: "#ffd43b"}. Colors set elsewhere in the config win over the theme.thresholdnumber|functionThe 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|functionAccessor for the value used in the threshold algorithm. A stacked Plot defaults to its stacked value.
thresholdNamestring|functionLabel for the threshold group, or a
(datum, index)accessor.timestring|false|functionAccessor function or string key for the time dimension of each data point.
timeFilterfalse|functionPredicate filtering which time slices are shown, or false to disable. With
timeset and notimeFilter, a chart starts on its latest period, or ontimelineDefault/timelineConfig.selection; setting it starts the chart (and its timeline) on the periods it keeps. A viewer's pick on the timeline replaces it.timelinebooleanDefaulttrueWhether to show the timeline component.
timelineConfigtimelineconfigConfiguration object for the timeline.
timelineDefaultstring|date|array.<string|date>The starting time or range for the timeline, which the chart starts on too. Can be a single Date/String, or an Array of 2 values representing the min and max. A viewer's pick on the timeline replaces it.
timelinePaddingboolean|functionTells the timeline whether or not to use the internal padding defined by the visualization in it's positioning. For example, d3plus-plot will add padding on the left so that the timeline appears centered underneath the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
titlestring|functionAccessor function or string for the visualization's title.
titleConfigrecordCSS style configuration for the title.
titlePaddingboolean|functionTells the title whether or not to use the internal padding defined by the visualization in it's positioning. For example, d3plus-plot will add padding on the left so that the title appears centered above the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
tooltipboolean|functionWhether to show tooltips, or a
(datum, index, {depth, maxDepth, legend})accessor deciding per mark and legend entry.depthis thegroupBylevel (from 0) the hovered item stands for andmaxDepththe deepest level, sodepth === maxDepthkeeps tooltips to the deepest level;legendis true for a legend entry. Defaults totrue.tooltipConfigtooltipconfigDefault{tbody: wordCloudTooltipRows(viz)}Configuration for the tooltip component.
totalstring|boolean|functionAccessor function or string key for the total value displayed in the visualization.
totalConfigrecordConfiguration object for the total bar.
totalFormatfunctionFormatter function for the value in the total bar.
totalPaddingboolean|functionTells the total whether or not to use the internal padding defined by the visualization in it's positioning. For example, d3plus-plot will add padding on the left so that the total appears centered above the x-axis. By default, this padding is only applied on screens larger than 600 pixels wide.
translatefunctionDefines 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. A string with numbered placeholders (
"{0} hidden") has them filled from the arguments after the locale, so each language can order its words naturally. If you'd like to override to use custom text, simply pass this method your own custom formatting function.widthnumberOverall width of the visualization in pixels.
wordPaddingnumberDefault2The clearance, in pixels, kept around each word's glyphs.
zoombooleanDefaulttrueEnables pan and zoom: the mouse wheel or a pinch (see
zoomScroll), a drag (seezoomDrag), a double-click (seezoomDoubleClick), the zoom-control buttons (seezoomControls), and thezoomIn,zoomOut,zoomReset, andzoomBrushmethods. On by default for every chart;falseturns all of them off.zoomBrushbooleanTurns brush mode on or off, as the brush button does: while it is on, a drag anywhere on the chart draws a box, and releasing zooms into the box and turns brush mode off again. With no argument, returns whether brush mode is on. Does nothing while
zoomis off or before the chart first renders.zoomBrushHandleSizenumberDefault1The pixel stroke-width of the zoom brush area.
zoomBrushHandleStylerecord|falseAn object containing CSS key/value pairs that is used to style the outer handle area of the zoom brush. Passing
falsewill remove all default styling.zoomBrushSelectionStylerecord|falseAn object containing CSS key/value pairs that is used to style the inner selection area of the zoom brush. Passing
falsewill remove all default styling.zoomControlClassNamestringAn additional CSS class name (or space-separated list of class names) applied to each zoom control button, alongside the fixed
zoom-control/zoom-in/zoom-out/zoom-reset/zoom-brush/select-box/select-lasso/zoom-moreclasses. Setting this automatically disables d3plus's built-in inlinezoomControlStyle/zoomControlStyleActive/zoomControlStyleHoverdefaults (as long as you haven't already customized them yourself), so a host page's own button styling — Tailwind, Bootstrap, a design system — applies through the cascade with no other configuration needed.zoomControlIconspartialOverrides the zoom-control icons (
zoomIn,zoomOut,zoomReset,zoomBrush,selectBox,selectLasso). Each value is an HTML string, or a mount function(el) => void | (() => void)called with the button's 12×12px icon slot (for a React tree, an<img>, …); a returned cleanup runs when the buttons redraw.zoomControlStylerecord|falseAn object containing CSS key/value pairs that is used to style each zoom control button (
.zoom-in,.zoom-out,.zoom-reset, and.zoom-brush). Passingfalsewill remove all default styling. Automatically skipped (as iffalse) once.zoomControlClassName(...)is set, unless you've explicitly customized this yourself.zoomControlStyleActiverecord|falseAn object containing CSS key/value pairs that is used to style each zoom control button when active (
.zoom-in,.zoom-out,.zoom-reset, and.zoom-brush). Passingfalsewill remove all default styling. Automatically skipped (as iffalse) once.zoomControlClassName(...)is set, unless you've explicitly customized this yourself.zoomControlStyleHoverrecord|falseDefaultfalseAn object containing CSS key/value pairs that is used to style each zoom control button on hover (
.zoom-in,.zoom-out,.zoom-reset, and.zoom-brush). Passingfalsewill remove all default styling. Automatically skipped (as iffalse) once.zoomControlClassName(...)is set, unless you've explicitly customized this yourself.zoomControlsbooleanDefaulttrueWhether the zoom-control buttons (zoom in, zoom out, reset, brush, and the box and lasso select tools, see
selectMode) show in the chart's top-right corner; on a chart too narrow for all of them beside the top-left controls, the ones that don't fit move into a "More Controls" menu.falsehides them and gives the room they take back to the chart's title, legend, and other top content, while zooming stays on: the wheel, pinch, drag, and double-click gestures still work, and the chart'szoomIn,zoomOut,zoomReset, andzoomBrushmethods let buttons of your own drive it. Defaults totrue.zoomDoubleClick"in"|"reset"|falseDefaultinWhat a double-click on the chart does:
"in"(the default) doubles the zoom around the pointer (Shift + double-click halves it),"reset"returns to the chart's initial view, like the reset button, andfalsedoes nothing.zoomDrag"pan"|"brush"DefaultpanWhat a mouse drag on the chart does.
"pan"(the default) pans it (seezoomPan)."brush"draws a box and zooms into it on release, as the brush button does, without turning brush mode on: a click that doesn't drag still reaches the shape under it, and hovering still shows tooltips. Shift + drag pans in"brush"mode, and touch keeps panning and pinching as in"pan".zoomFactornumberDefault2Multiplier applied to programmatic zoom steps.
zoomMaxnumberMaximum zoom scale factor. Defaults to the scale at which the smallest shape fills the chart area.
zoomPaddingnumberDefault20A pixel value to be used to pad all sides of a zoomed area. A Plot's brushed box fills its plot without it, so its axes show the brushed range.
zoomPanbooleanDefaulttrueWhether panning (drag) is enabled while zoomed.
zoomScrollboolean|"modifier"DefaultmodifierWhether the mouse wheel (and one-finger touch) zooms.
"modifier"(the default) leaves page scrolling alone: only Ctrl/⌘ + wheel or a trackpad/two-finger pinch zooms, and one finger pans only once zoomed in.truezooms on any wheel;falsenever does.