BubbleChart
Creates a bubble chart from an array of data: each row draws as a circle
at its x and y values, sized by its size value. Bubbles are sized by
area (sizeZero with a "sqrt" sizeScale): a value twice as large
draws a bubble with twice the area, and the largest draws at sizeMax
pixels in radius. A size legend keys the sizes, larger bubbles are drawn
first so smaller ones stay on top, and each bubble is outlined in the
chart’s background color so overlapping bubbles stay distinct.
Basic example
Section titled “Basic example”Each row draws as a bubble at its x and y values, sized by its size value. Bubbles are sized by area: India’s bubble has about five times the area of Indonesia’s, as its population is about five times larger. The size legend in the bottom-right corner keys the sizes, larger bubbles are drawn first so smaller ones stay on top, and each bubble is outlined in the chart’s background color.
The largest bubble's radius, in pixels.
Radius range
Section titled “Radius range”Set sizeZero to false to spread the radii between sizeMin and sizeMax instead. The smallest bubble grows to sizeMin, which keeps small values easy to see and hover, but areas no longer compare as values do.
Anchors a Plot's size scale at zero, so a mark's size is proportional to its value: with the default sizeScale of "sqrt", each circle's area is (a value twice as large draws a circle with twice the area), and with "linear", its radius. The largest value still draws at sizeMax, while sizeMin no longer sets the smallest mark's radius, so values near zero draw as small as they are. Off by default, except on BubbleChart. Ignored when any size is negative or sizeScale is "log".
The size scale starts at zero, so each bubble's area is proportional to its value.
The largest bubble's radius, in pixels.
Radii follow the square root of size, so areas follow the value.
Overlap style
Section titled “Overlap style”shapeConfig.Circle styles the bubbles. A translucent fill shows the bubbles hidden behind others, and a wider outline separates them further.
const countries = [
["Brazil", "Americas", 15.1, 75.9, 216],
["Canada", "Americas", 53.4, 82.6, 39],
["Mexico", "Americas", 21.5, 75.0, 128],
["United States", "Americas", 74.6, 79.3, 335],
["China", "Asia", 21.5, 78.6, 1410],
["India", "Asia", 8.4, 72.0, 1429],
["Indonesia", "Asia", 13.4, 71.7, 278],
["Japan", "Asia", 45.6, 84.7, 124],
["France", "Europe", 50.9, 83.3, 68],
["Germany", "Europe", 58.9, 81.4, 84],
["Italy", "Europe", 46.8, 83.7, 59],
["Egypt", "Africa", 15.1, 70.2, 113],
["Ethiopia", "Africa", 2.8, 67.3, 127],
["Nigeria", "Africa", 5.6, 54.5, 224],
["South Africa", "Africa", 14.0, 66.1, 60],
].map(([country, region, gdp, life, pop]) => ({
country,
region,
"GDP per Capita ($K)": gdp,
"Life Expectancy": life,
"Population (M)": pop,
}));
const config = {
data: countries,
groupBy: ["region", "country"],
size: "Population (M)",
x: "GDP per Capita ($K)",
y: "Life Expectancy",
shapeConfig: {Circle: {fillOpacity: 0.7, strokeWidth: 2}},
};
Configuration
import {BubbleChart} from "@d3plus/core";
activefalse|functionThe active callback function for highlighting shapes.
aggsobjectCustom aggregation functions keyed by data property.
annotationsunknownDefaultunknownAllows drawing custom shapes to be used as annotations in the provided x/y plot. This method accepts custom config objects for the Shape class, either a single config object or an array of config objects. Each config object requires an additional parameter, the "shape", which denotes which Shape sub-class to use (Rect, Line, etc).
Additionally, each config object can also contain an optional "layer" key, which defines whether the annotations will be displayed in "front" or in "back" of the primary visualization shapes. This value defaults to "back" if not present ("front" for callouts).
Three more kinds draw chart notes:
"Callout"anchors wrapped text in a box at each data row'sx/y(in data units, or plot-area fractions withxRef/yRef: "plot"), offset bydx/dypixels and joined to its anchor by a connector ending in an arrowhead or dot (seeCalloutAnnotation);"ReferenceLine"and"ReferenceBand"draw whatreferenceLinesandreferenceBandsentries expand into. All annotations follow zoom and never respond to the pointer or keyboard.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.
axisHoverboolean|"x"|"y"DefaulttrueWhether hovering a Plot's mark draws a dashed guide from its point to each axis and a badge on that axis with the point's value there, formatted as the tooltip formats that axis's values (the axis's
tickFormatwhen set)."x"or"y"draws them for that direction only (each including its secondary axis). A bar is badged on its value axis only. With a discrete axis, the shared tooltip's crosshair is that axis's guide, and the value axis follows the hovered series' point (or the one nearest the pointer). Defaults totrue("x"on BumpChart, whose y axes label series rather than values, and on Streamgraph, whose y positions name no values).axisHoverConfigobjectStyles the
axisHoverguides and badges.guideConfigtakesstroke(the hovered mark's color by default),strokeWidth(default1),strokeDasharray(default"4 3"), andstrokeOpacity.badgeConfigtakesfill(the hovered mark's color by default),fontColor(a color contrasting the fill by default),fontFamily,fontSize(default12),fontWeight(default400),paddingaround the text (default4), andrxcorner radius (default2). Each is a value or a(d, i) => valueaccessor of the hovered data row.axisPersistbooleanDefaultunknownDetermines whether the x and y axes should have their scales persist while users filter the data, the timeline being the prime example (set this to
trueto make the axes stay consistent when the timeline changes).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.backgroundConfigrecordDefault{duration: 0, fill: transparent}A d3plus-shape configuration Object used for styling the background rectangle of the inner x/y plot (behind all of the shapes and gridlines).
barPaddingnumberDefault0Padding between bars in pixels.
baselinenumberStarts the value axis (the x axis for horizontal charts) at a value:
baseline(n)renders exactly likeyDomain([n])(orxDomain([n])). Bars, areas, and stems still grow from the chart's own0in the Plots that draw from one (such as BarChart, AreaPlot, Histogram, and Lollipop), so withbaselineBreakon (their default) the axis breaks back to a0tick and bars run through the break, with its gap cut across them, and with it off the axis stretches down to0. As withyDomain([n]), onlynis pinned: the far end comes from the data and is rounded where the axis would round it with no domain set (left at the data when the axis config'sroundingis "none"), and marks for values pastnstop at the axis's edge. When every value sits at or belown, it ends the axis instead, likeyDomain([undefined, n]). A bound given inyDomain/xDomainwins. Returns the chart's own baseline when none is set.baselineBreakbooleanWhen the domain of a linear value axis stops short of the
baseline(e.g.[1100, 2100]with a baseline of0), keeps the baseline as the axis's end tick and breaks the axis between it and the domain: a short stretch of axis holds the baseline tick and two tilted marks with a gap in the axis line, then the domain spans the rest. Style it with the axis'sbaselineBreakConfig. In a Plot it applies to a user-supplied value domain (yDomain/yConfig.domain, or the x versions for horizontal charts), and bars and areas start at the baseline tick, with the break's gap cut across them (baselineBreakConfig'smask); turned off, ayDomainstretches to reach the baseline while ayConfig.domainis kept and cuts its bars off at the axis. Defaults totruefor the Plots whose marks grow from0, such as BarChart, AreaPlot, Histogram, and Lollipop (each chart lists its own default), andfalsefor other Plots and a standalone Axis.bufferboolean|recordDefaultassign({}, defaultBuffers, {Bar: false, Line: false})Determines whether or not to add additional padding at the ends of x or y scales. The most commone use for this is in Scatter Plots, so that the shapes do not appear directly on the axis itself. The value provided can either be
trueorfalseto toggle the behavior for all shape types, or a keyed Object for each shape type (ie.{Bar: false, Circle: true, Line: false}).cachebooleanDefaulttrueWhether the chart keeps the files it fetches for
data,links,nodes,topojson, andfitObject. Each chart has its own cache of its 10 most recent requests, keyed by the request (the URL, and a request object'sfetchoptions), so loaders naming the same URL share one request. It holds each response as fetched, before its*Formatformatter runs, so setting the same URL again, or a new formatter, draws from the cache without a request. A failed request is not kept. Defaults totrue; set it tofalseto fetch on every load, or usedataPollingIntervalto re-fetchdataon a schedule (polls always fetch).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|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.
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.confidenceunknownThe confidence interval as an array of [lower, upper] bounds. Lines draw it as a shaded band; bars draw an error bar per bar, from the lower to the upper bound with a cap at each end (a stacked bar's bounds keep their distance from its value, measured from the bar's stacked end). Either bound may be
falsefor a one-sided interval, and a row without a bound pinches the band onto its line. The value axis widens to fit the bounds, and tooltips list them (seeconfidenceConfig.tooltip). Passfalseto turn the interval off.Pass an array of bands, outermost first, to draw nested bands around each line (a fan): each band is a
[lower, upper]pair or[lower, upper, label], or a{lower, upper, label}object, andconfidenceConfig.bandOpacityshades them from the widest (lightest) to the narrowest (darkest). Tooltips list each band's range under its label ("Band 1", "Band 2", … when unlabeled), and bars draw the first band's error bar.confidenceConfigrecordDefaultfunction{fill: (d, i) => { const { Line, stroke } = this.schema.shapeConfig; const s = Line && Line.stroke !== undefined ? Line.stroke : stroke; return typeof s === "function" ? s(d, i) : s; }, fillOpacity: 0.5}Configuration object for shapes rendered as confidence intervals. A line's band is an Area, filled with the line's color at half opacity. A bar's error bar is a Path styled by
stroke(default a shade darker than the bar),strokeWidth(default2),strokeDasharray,strokeOpacity, andcapWidth: the length of each end cap, in pixels or as a percentage string of the bar's thickness (default"50%"). Keys nested underAreaorBarapply only to that shape's interval. With several bands,bandOpacitysets how each band looks where it is the innermost band drawn: an array ramps from the outermost band to the innermost (default[0.15, 0.6]), a number gives every band that opacity, and either replacesfillOpacity.tooltip(defaulttrue) lists the bounds in tooltips: a "Lower Bound" and "Upper Bound" row for a single mark, and a range after each series' value in a shared tooltip; set it tofalseto leave them out. Accepted keys: any key the Area or Path shape takes at the top level, plusbandOpacity,capWidth,tooltip,Area(Area keys), andBar(Path keys andcapWidth); any other key logs a warning.configd3plusconfigMethods that correspond to the key/value pairs and returns this class.
connectGapsconnectgapsDefaulttrueHow a line crosses a missing value: a step of the discrete axis that another line has and this one skips, or a row whose value is
nullorNaN.true(the default) or"solid"draws the line straight on through it.falsebreaks the line there, leaving the gap empty."dashed"breaks the line and bridges the gap with a short dash ("2 4") in the line's color, distinct from a forecast's longer dash. An object styles the bridge:stroke(default the line's color),strokeDasharray(default"2 4";falsefor a solid bridge),strokeWidth(default the line's width), andopacity(default1). A bridge follows the line's curve, since it is drawn along the same path, and is decoration only: it has no tooltip, takes no keyboard focus, and a shared tooltip at a missing step lists no value for that line. Confidence bands are clipped to the stretches between gaps. A point with a gap on both sides draws no line of its own, so turn onlineMarkersto show it. Areas, including stacked ones, are drawn as before.crosshairConfigrecordDefaultfunction{stroke: () => themed(this._theme, (t) => t.textMuted, colorGray.500), strokeDasharray: 4 3, strokeWidth: 1}Paint for the shared tooltip's crosshair guide line (
stroke,strokeWidth,strokeDasharray,strokeOpacity, …). Merged into the current config.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 (
[]).dataCutoffnumberDefault100Maximum number of data points to render before downsampling.
dataFormatfunctionTransforms
databefore it is drawn. The function receives the loaded file (or the parsed JSON response, or an Array of them whendatalists several URLs), or the Array passed asdata, and returns the rows to draw. It may instead return a config object holding the rows as itsdatakey, and the rest of that object is applied to the chart, so a response can set options such astitlefrom what it contains.It runs when the chart renders, whichever order
dataanddataFormatare set in, and setting it again re-runs it on the next render, over the cached response (seecache). EverydataPollingIntervalpoll runs it too. Passing a formatter as the second argument ofdata(url, format)sets it, and settingdataalone keeps it.dataPollingIntervalnumber|falseDefaultfalseWhen
datais loaded from a URL (or a request object, or an Array holding one), re-fetches it every this many milliseconds and redraws with a transition when it changes, keeping hover, zoom, legend toggles, and the timeline selection. Each poll uses the same request anddataFormatas the first load, and a response identical to the drawn data is not redrawn. Polling waits while the browser tab is hidden or, withdetectVisible, while the chart is scrolled out of view, and catches up as soon as it is visible again. A failed request keeps the last data, logs one warning per run of failures, and tries again on the next tick.destroy(), setting this tofalse, or passing newdatastops polling. Onlydatais polled, notlinks,nodes, ortopojson. 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.detectVisibleUnloadbooleanDefaulttrueWhen
true(the default) anddetectVisibleis enabled, the Viz releases its DOM and scene while it is scrolled out of view and redraws when it returns, keeping the page light when there are many visualizations. Data and configuration are retained; interaction state such as zoom or selection is not, so set this tofalseto keep it. WithdetectVisibleenabled, each chart's<svg>is also givencontent-visibility: auto, so the browser skips rendering its contents while it is far off-screen (this matters most when this isfalseand charts are kept). For a larger saving you can also applycontent-visibility: autoand acontain-intrinsic-sizeto the container element yourself; that adds paint containment to an element you own, so it is not done automatically. RequiresIntersectionObserver.discrete"x"|"y"|"radius"|"angle"Sets orientation of main category axis.
discreteCutoffnumberDefaultunknownWhen the width or height of the chart is less than or equal to this pixel value, the discrete axis will not be shown. This helps produce slick sparklines. Set this value to
0to disable the behavior entirely.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 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) => stringfunction for each panel's title, orfalseto hide panel titles. -titleConfig: TextBox config for the panel titles (fontSize,fontWeight,fontColor,textAnchor,padding, …).fillBetweenboolean|[string|number, string|number]|array.<[string|number, string|number]>DefaultfalseFills the area between two series' lines, in the color of whichever series is higher, switching color where the lines cross:
truefills between the first two series,[a, b]between the series with idsaandb, and a list of[a, b]pairs fills between each pair. The fill follows the lines' curve and leaves pointer events to the lines. Defaults tofalse.fillBetweenConfigrecordArea styles for
fillBetween(default{fillOpacity: 0.25}). Style accessors receive a data row of whichever series is higher, withaboveandbelowkeys naming the higher and lower series, so afillaccessor can color the A > B and B > A regions apart. Like a confidence band, the fill takestexture,textureDefault,backgroundImage, andbackgroundImageFitfromshapeConfig(orshapeConfig.Area), so a texture accessor that picks a series textures the regions where that series is higher; set them here to style the fill alone, or tofalseto keep it plain.filterfalse|functionPredicate filtering which data points are included, or false to disable.
fontFamilystring|array.<string>The font family used throughout the visualization.
forecastboolean|number|string|date|functionMarks a forecast: the stretch of the discrete axis after it gets a shaded backdrop, a rule at its start, and a translated "Forecast" label, and each line's forecast stretch is dashed (see
forecastConfig). A function flags the forecast rows (e.g.d => d.Type === "Predicted"): each line is dashed from its last unflagged point, or throughout when every row is flagged, and the backdrop starts at the earliest of those."auto"(ortrue) flags the rows whoseconfidencebounds spread away from their line. A discrete-axis value (a date or year on a time axis) starts the forecast there. Unset (the default), only a trend line projection (trendLineConfig.projection) is marked, from the last fitted value;falsemarks nothing, not even a projection. On bar charts the backdrop starts at the edge of the first forecast bar, and bars keep their own styles. Defaults to"auto"on a FanChart.forecastConfigrecordStyles for the
forecastmarker: the backdrop'sfillandfillOpacity(default0.05;fill: falsehides it), the rule'sstroke,strokeWidth(1),strokeOpacity(0.4), andstrokeDasharray("4 4";stroke: falsehides it), the label's text aslabel(default "Forecast", translated;falsehides it) withfontColor,fontFamily,fontSize(12),fontWeight, andfontOpacity(0.7), andlineDasharray, the dash pattern of each line's forecast stretch (default"6 4";falsekeeps lines solid). Colors default to the chart's text color for its background. The backdrop is chart chrome with no data row, soshapeConfig.textureandshapeConfig.backgroundImageleave it plain; give it its owntexture(a textures.js name or config, drawn in the backdrop's color over its shade attextureOpacity, default0.3, withtextureDefault) orbackgroundImage(a URL, fit bybackgroundImageFit,"cover"or"contain"). Both are off by default.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.
groupPaddingnumberDefaultunknownThe pixel space between groups of bars.
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, in pixels, the pointer has to come to a point mark for it to count as hovering that point. Over empty space, or over something other than a point (a gridline, a link), the pointer acts on the closest point whose edge lies within this distance: its tooltip, hover highlight, and axis guides show, and a click there clicks it. A point's tooltip points at the top of the point (on it or near it) and holds still until another point takes over. Applies to the point marks of scatter and bubble plots (Circle and Rect shapes, Beeswarm included), Network nodes, and Geomap points; bars, areas, lines, and other area-filling marks keep exact hit-testing. Plots with a discrete axis and
tooltipSharedon snap to the nearest column instead. Defaults to20;0turns it off, along with the anchored tooltip.Lets keyboard users move between the chart's data marks. The chart is one Tab stop (a focusable
role="application"element laid over it, named bysvgTitleor the chart'stitle); once it has focus, the arrow keys move to the nearest mark in that direction, Home and End jump to the first and last mark, 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, a ring outlines it (seekeyboardNavConfig), and a live region announces its label to screen readers. Legend items are included after the chart's marks; Line and Area series are visited point by point. On by default;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).labelConnectorConfigrecordDefault{strokeDasharray: 1 1}The d3plus-shape config used on the Line shapes created to connect lineLabels to the end of their associated Line path.
labelPosition"auto"|"along"|"inside"|"outside"|functionWhere each shape's label goes, as a string for every shape or a
(d, i) => stringaccessor of the data row.- Ring segments (Donut slices and those of a Pie with an
innerRadius, Sunburst arcs, Chord groups, and RadialBar tracks):"along"runs a segment's name along its arc, following the ring, reading left to right on the bottom half as on the top."auto"picks, segment by segment, whichever reads better: the curve when its arc is long enough for the whole name and it shows it larger than a straight label could (a thin ring), the straight label when that fits as well, and a curve cut short with an ellipsis when nothing else fits. A full Pie (noinnerRadius) keeps its labels inside straight: its wedges run to a point at the center. On a Pie or Donut (anyinnerRadius, and partial rings such as a half pie), a slice whose label inside can't show its whole name under"auto"is labelled outside the ring instead, and"outside"labels every slice there: its name and share, horizontal, in the PathlabelConfig's font at itsfontSize(12px by default), in the theme's text color unlesslabelConfig.fontColorsets one, joined to the slice by a thin leader line. These labels stack in a column on the side of the ring their slice faces, wrapping onto a second line between words when their column is narrow; the ring shrinks (its hole with it) to leave room for them, never below 60% of its full radius, and when they don't all fit, the smallest slices' labels are left out (those slices keep their label inside, if any)."inside"keeps a Pie or Donut's labels straight inside their slices, and on the other ring segments both"inside"and"outside"keep the straight labels. A Donut's curves follow the middle of its ring (the rim, when its hole is small), with the slice's share on a smaller second line when there is room. A Sunburst also weighs a label turned along its radius, which suits the narrow arcs of the outer rings. Curved Donut and Sunburst names keep 5px from the ring's edges and at least 0.3em from the segment's ends, at the largest size from the PathlabelConfig'sfontSize(elsefontMax, 24px by default) down to itsfontMin(8px). A Chord curves its group names just outside the ring when every name fits along its arc, which leaves the ring more room; otherwise it curves those that fit and turns the rest along their spokes, all at the PathlabelConfig'sfontSize(11px by default). A Radar does the same with its metric names, just outside the web, each between its neighbors' spokes, wrapping a long name onto a second curved line. A RadialBar curves each track's name along the track, inside its bar (or past its end when the bar is too short), when the sweep leaves no room before the start for the straight labels, and at any sweep for"along"; when every track is named this way, the default legend hides. Curved text takes the color that contrasts with what lies under it (the theme's ink outside the ring) and dims with its segment on hover. A label with no room is left out. - Bars:"inside"or"outside"the bar, or"auto", which goes outside when the bar is shorter than half the room along its axis. Stacked bars always label inside. - Circles (scatter and bubble points, Beeswarm points given alabel, Network nodes, and Geomap coordinate points):"auto"keeps a label inside its circle when it fits there atpointLabelConfig.fontMinor larger, else moves it beside the circle, else hides it. A Network or Geomap's labels beside their circles stay in the chart area, a Plot's in its plot area."inside"keeps every label inside, shrinking it to fit (a label that can't fit is dropped)."outside"always puts it beside the circle. A label goes beside its circle on the side with the most open room: the side facing its Voronoi cell's centroid first, then right, left, top, bottom, and the diagonals. A side is taken only where the label lies mostly in the circle's Voronoi cell, stays in that area, and overlaps no circle and no label placed before it. Larger circles are placed first. A label with no room is hidden; the circle's tooltip and aria-label still name it. Geomap points are labeled byshapeConfig.Circle.labelwhen it is set (falseturns their labels off), else bylabel. Labels are placed when the chart draws: a zoomed Plot places them again for its new scales, while a zoomed Network or Geomap scales them with the picture. - Stacked areas (StackedArea, Streamgraph, and a stacked AreaPlot):"auto"or"along"runs each series' name along its band's centerline, following its curve, on the stretch where the band is at least the font size plus 4px thick under the whole label and flattest. The text reads upright, in the color that contrasts with the band's fill (or the ArealabelConfig'sfontColor, when you set one), and dims with its band on hover. It starts at the ArealabelConfig'sfontSize(orfontMax, else 16px) and shrinks a pixel at a time down to itsfontMin, but no lower than 8px, before giving up; a band too thin for its name everywhere goes unlabeled. When every band gets a name, the default legend hides (alegendof your own always wins, and the legend stays while a series is hidden from it)."inside"(or"outside") puts the label in the band's largest box instead.shapeConfig.Area.labelsets the text, orfalsefor none.Defaults to
"auto".legendboolean|functionWhether to display the legend. By default, the legend shows when it has more than one entry and each entry stands for a single group (or two groups at most), or when the entries are colored by a category that isn't a
groupBylevel (seecolor), in which case each entry is labelled by its category. Passfalseto hide it,trueto always show it, or a(config, data) => booleanfunction to decide.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. A click or shift+click (or Enter or Space on a legend item) that changes what is hidden or solo'd shows the Back button, and Back undoes legend clicks and drill-downs in the order they happened, restoring the legend exactly as it was. A drill-down to a deeper level starts with every group shown, and Back out of it brings back the legend it left. A click that changes nothing adds no step, and new
dataclears the legend's steps along with the legend. Clicking a Sunburst or Icicle center zooms out without undoing the legend clicks made since the zoom. Defaults totrue;falseleaves legend clicks off the history, so Back only steps out of drill-downs.legendInsetboolean|functionDefaulttrueWhether the chart may draw one of its legends inside the empty space around its marks instead of in a margin, for charts that leave open space around their marks, such as Plot and the charts built on it, Network, Pack, Pie, and Geomap; a chart whose marks fill its area, like Treemap, keeps its legends in the margins. After the chart lays out, the size legend is tried first, then the legend, then the colorScale; the first that fits is drawn over a semi-transparent box (see
legendInsetConfig), and any others keep their margins. Space enclosed by the marks, like the middle of a ring of points, is never used. Only a legend or colorScale whose position is"auto"(the default) can move inside; one set to a side stays in that margin. Defaults totrue; also accepts a function that receives the resolved chart config and returns a boolean.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.legendSortfunctionComparator 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.legendTooltiptooltipconfigConfiguration object for the legend tooltip.
lineLabelConfiglinelabelconfigOptions for
lineLabels.value: trueadds the line's value at each labeled end after the series name (e.g. "Brazil 37%"), formatted as the y axis formats its ticks (itstickFormatwhen set).valueFormatformats it instead, as a function of the value, the row it belongs to, and the row's index. Defaults to{value: false}.lineLabelslinelabelssettingLabels each line of a line chart with its series name, just past the line's ends:
trueor"end"labels the right end,"start"the left end, and"both"both ends. A function of each row returns any of these (orfalse) to choose per series. The plot leaves room for the labels on the side they sit, at most a quarter of its width past the y axis per side; a label wider than that drops its value, then shortens its name with an ellipsis, then hides. Labels that would overlap are moved apart, each side on its own, with a dotted connector back to their line; when the plot is too short for them all, the last that fits reads "+N more".lineLabelConfigadds each end's value to its label."along"writes each series name along its own line instead, following its curve: on the stretch that bends and slopes least and stays clear of the other lines and labels, reading upright whichever way the line runs. A line with no clear stretch for its name goes unlabeled, a chart (or small-multiples panel) with a single line names none, and the plot leaves no room past the lines for these labels. The Line shape'slabelConfigsets theirfontSize,fontFamily, andfontWeight. When every line gets a name, the default legend hides (alegendof your own always wins). LinePlot defaults to"along"; other charts default to no labels.lineMarkerConfigrecordDefaultfunction{fill: (d, i) => colorAssign(this._id(d, i), linkedColorDefaults(this)), r: 3}Shape config for the Circle shapes drawn by the lineMarkers method.
lineMarkersbooleanDefaultunknownDraws circle markers on each vertex of a Line.
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 underneath the zoom controls 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.referenceBandsarray.<referencebandconfig>Default[]Plot: shaded spans across the plot between two values, such as a recession or a target range. Give each entry
x(a vertical band) ory(a horizontal one) as[start, end]in data units (numbers, dates, or categories; on a category axis the band covers each end category's whole slot), orx2/y2for the secondary axes, orref: "plot"for fractions of the plot area. An optionallabelsits inside the band's top-left corner (labelPosition: "end"for the top-right), withfontColor,fontFamily,fontSize,fontWeight,lineHeight, andmaxWidth. The fill defaults to the chart's text color atfillOpacity0.08, so it reads on light and dark themes;stroke,strokeWidth, andstrokeOpacityadd edges. On a continuous or time axis the band's ends count toward the axis domain, widening it to show the whole band (an end set byxDomain/yDomain/x2Domain/y2Domainor the axis config'sdomainstays put). Each entry expands into a"ReferenceBand"annotation (seeannotations) behind the data (layer: "front"to draw it over; its label always draws above), which follows zoom and never responds to the pointer or keyboard. A label that would cover a data label or another reference label moves to the band's other corners or along its length, inside the plot, and is hidden when no spot is free.referenceLinesarray.<referencelineconfig>Default[]Plot: lines across the whole plot at one value, such as a target or a launch date. Give each entry
x(a vertical line) ory(a horizontal one) in data units (a number, a date, or a category), orx2/y2for the secondary axes, orref: "plot"for a fraction of the plot area. An optionallabelsits at the line's"end"(the right of a horizontal line, the top of a vertical one) or"start"(labelPosition), withfontColor,fontFamily,fontSize,fontWeight,lineHeight, andmaxWidth. The line'sstrokedefaults to the chart's text color atstrokeOpacity0.6,strokeWidth1;dash: truedashes it ("4 4"), or give a dash pattern. On a continuous or time axis the value counts toward the axis domain, widening it to show the line (an end set byxDomain/yDomain/x2Domain/y2Domainor the axis config'sdomainstays put; a value outside such a domain is not drawn). Each entry expands into a"ReferenceLine"annotation (seeannotations) behind the data (layer: "front"to draw it over; its label always draws above), which follows zoom and never responds to the pointer or keyboard. A label that would cover a data label or another reference label moves to the line's other side or end, or along it, inside the plot, and is hidden when no spot is free.renderfunctionDraws 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".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.shapeConfigd3plusconfigDefault{Circle: {stroke: () => chartBackground(viz), strokeWidth: constant(1)}}Configuration object with key/value pairs applied as method calls on each shape.
Each bubble is outlined in the chart's background color, so overlapping bubbles stay distinct.
shapeSortfunctionA sort comparator that receives each shape class (e.g. "Circle", "Line") as its arguments. Shapes are drawn in groups by type, so this defines the layering order for all shapes of a given type.
sizefalse|plotaccessorargSets the size of bubbles to the given Number, data key, or function.
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 viapointSize, 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.sizeMaxnumberDefault40The largest bubble's radius, in pixels.
sizeMinnumberDefault5sizeScalestringDefaultsqrtRadii follow the square root of
size, so areas follow the value.sizeZerobooleanDefaulttrueAnchors a Plot's size scale at zero, so a mark's size is proportional to its value: with the default
sizeScaleof"sqrt", each circle's area is (a value twice as large draws a circle with twice the area), and with"linear", its radius. The largest value still draws atsizeMax, whilesizeMinno longer sets the smallest mark's radius, so values near zero draw as small as they are. Off by default, except on BubbleChart. Ignored when any size is negative orsizeScaleis"log".The size scale starts at zero, so each bubble's area is proportional to its value.
stackOffsetstring|stackoffsetfnDefaultstackOffsetDivergingSets the vertical offset applied to stacked series. Accepts a named offset —
"diverging"(default),"none","expand","silhouette", or"wiggle"— or a custom offset function. Unknown names warn and fall back to"diverging". If value is not specified, returns the current stack offset function.stackOrderstackorderinputDefaultstackOrderTotalDescendingSets the order of stacked series, from the bottom of the stack upward. Accepts: - a named order:
"descending"(default) /"ascending"by summed value,"key"/"keyReverse"alphabetically by series key,"none"/"data"for input order, or d3's"insideOut","appearance","reverse"; - an Array of series keys for an explicit order; - a value accessor, or a{value, order}config, to rank series by an aggregate of any data field.Unknown named strings warn and fall back to
"descending". The default legend lists the series in the order they stack, from the baseline outward. If value is not specified, returns the current stack order.stackedbooleanWhether to stack series.
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>).swarmboolean|"auto"|"x"|"y"DefaultautoPacks a Plot's circles into a beeswarm: each circle keeps its value along one axis and is placed beside its neighbors along the other, so none overlap.
"x"or"y"names the value axis;trueuses x when its values are numeric, else y;falsedraws a plain scatter. When the other axis holds categories (strings), each category gets its own swarm in its own band; otherwise that axis's values are ignored and its axis is hidden. Circles keep their ids, so switching a chart betweenfalseandtrueanimates each circle between its scatter and swarm position. The default,"auto", swarms only when every mark is a Circle and every row lacks a y (or x) value.swarmConfigobjectOptions for
swarm:padding, the minimum pixel gap between circles (default1), andoverflow, what happens when a swarm is wider than its band —"shrink"(default) scales every circle down until each swarm fits,"clamp"keeps the sizes and holds outlying circles at the band's edge, and"visible"lets swarms spill past their band.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 behind the chart: its chrome text contrasts with the page, its tooltip, table view, and overlays turn dark on a dark page, and it redraws when the page flips between light and dark."light"and"dark"paint the theme's background behind the chart (so it reads the same on any page, and in a saved image) and take every chrome color from the theme. An object sets your own tokens on top of the preset itsbasenames ("light"or"dark"), for example{base: "dark", background: "#123", accent: "#ffd43b"}. A dark theme also turns color scale ramps around, from a dim tint near the background up to a bright pole (see thecolorScaletokens). Colors you set in the other config (titleConfig.fontColor,tooltipConfig,colorScaleConfig.colorMax, the*Styleoptions, …) 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)accessor deciding per mark.tooltipConfigtooltipconfigConfiguration for the tooltip component.
Whether hovering a Plot's plot area shows one tooltip listing every series' value at the nearest discrete-axis position, with a crosshair through it. Applies when a discrete axis is set and at least two series share that position.
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. If you'd like to override to use custom text, simply pass this method your own custom formatting function.
trendLinetrendlinetypeDraws an automatic trend line fit to the plotted data:
true(or"linear") for a least-squares line, or one of"exponential","logarithmic","power", or"polynomial". By default each series gets its own line in its color; seetrendLineConfigfor grouping, a confidence band, and styling. On a chart with a discrete axis, the line runs along that axis, fitting categories by their order. Set tofalse(the default) to remove.trendLineConfigrecordOptions for the trend lines drawn by
trendLine, merged into the current config: -group:"series"(default) fits one line per series, colored to match it;"all"fits a single line to every point. -order: the polynomial degree whentrendLineis"polynomial"(default2). -confidence: draws a confidence band around a linear fit (defaultfalse). -confidenceLevel: the band's confidence level (default0.95). -confidenceConfig: Area shape config for the band (default{fillOpacity: 0.15}; fill defaults to the line color). -projection: extends each line past the end of its data, by a number of steps at the data's own spacing (e.g.5more years), or to an end value with{to: 2030}(default0, off). The axis widens to fit, and a linear fit's band becomes a prediction interval that fans out over the projection. Hovering a projected step lists each series' projected value. Ignored on a category axis. -projectionConfig: Line shape config for the projected stretch, over the line's own styles (default{strokeDasharray: "2 4"}). -tooltip: shows the fitted equation and R² when hovering a line (defaulttrue). - Any other key (stroke,strokeWidth,strokeDasharray, …) styles the Line shape.Stacked charts always fit one line to the stack totals.
widthnumberOverall width of the visualization in pixels.
xplotaccessorargDefaultfunctiond => d["x"]Accessor function or string key for the x-axis value of each data point.
x2plotaccessorargDefaultfunctiond => d["x2"]Accessor function or string key for the secondary x-axis value of each data point.
x2ConfigrecordDefault{}A pass-through to the underlying Axis config used for the secondary x-axis. Includes additional functionality where passing "auto" as the value for the scale method will determine if the scale should be "linear" or "log" based on the provided data.
x2Domainarray.<number|date>The x2 domain as an array. If either value is undefined, it is calculated from the data.
x2SortfunctionDefines a custom sorting comparator function for discrete x2 axes.
xBreak[number, number]|array.<[number, number]>Value range(s) to remove from the x axis —
[start, end]or a list of them — drawn as a break in the axis with a gap cut across the shapes that cross it (see the axisbreakandbreakConfig).xConfigrecordDefaultfunction{gridConfig: {stroke: (d) => { if (this.schema.discrete?.charAt(0) === "x" || this._swarm?.cross === "x") return "transparent"; const range = this._xAxis.range(); const position = this._xAxis._getPosition.bind(this._xAxis)(d.id); if (range[0] === position) return "transparent"; return chartGridline(this); }}}A pass-through to the underlying Axis config used for the x-axis. Includes additional functionality where passing "auto" as the value for the scale method will determine if the scale should be "linear" or "log" based on the provided data.
xCutoffnumberDefault150xDomainarray.<string|number|date>The x domain as an array. On a continuous axis it is
[min, max]. Setting just one end ([min]or[undefined, max]) pins only that end: the data fills the other, rounded where the axis would round it with no domain set (left at the data whenxConfig'sroundingis "none"; time axes aren't rounded). With both ends set, neither is rounded. On a discrete axis it lists the categories to show, in order; data in other categories is not drawn. A fullxConfigdomainis the lower-level override: it wins over this, and is drawn exactly as given (rounded only byxConfig's ownrounding), without stretching to the chart'sbaseline.xSortfunctionCustom sort function for x-axis values.
yplotaccessorargDefaultfunctiond => d["y"]Accessor function or string key for the y-axis value of each data point.
y2plotaccessorargDefaultfunctiond => d["y2"]Accessor function or string key for the secondary y-axis value of each data point.
y2ConfigrecordDefault{}A pass-through to the underlying Axis config used for the secondary y-axis. Includes additional functionality where passing "auto" as the value for the scale method will determine if the scale should be "linear" or "log" based on the provided data.
y2Domainarray.<number|date>The y2 domain as an array. If either value is undefined, it is calculated from the data.
y2SortfunctionDefines a custom sorting comparator function for discrete y2 axes.
yBreak[number, number]|array.<[number, number]>Value range(s) to remove from the y axis —
[start, end]or a list of them, e.g.[100, 900]to fit one outlier bar — drawn as a break in the axis with a gap cut across the shapes that cross it (see the axisbreakandbreakConfig).yConfigrecordDefaultfunction{gridConfig: {stroke: (d) => { if (this.schema.discrete?.charAt(0) === "y" || this._swarm?.cross === "y") return "transparent"; const range = this._yAxis.range(); const position = this._yAxis._getPosition.bind(this._yAxis)(d.id); if (range[range.length - 1] === position) return "transparent"; return chartGridline(this); }}}A pass-through to the underlying Axis config used for the y-axis. Includes additional functionality where passing "auto" as the value for the scale method will determine if the scale should be "linear" or "log" based on the provided data.
Note: If a "domain" array is passed to the y-axis config, it will be reversed.
yCutoffnumberDefault150yDomainarray.<string|number|date>The y domain as an array. On a continuous axis it is
[min, max]. Setting just one end ([min]or[undefined, max]) pins only that end: the data fills the other, rounded where the axis would round it with no domain set (left at the data whenyConfig'sroundingis "none"; time axes aren't rounded). With both ends set, neither is rounded. On a discrete axis it lists the categories to show, in order; data in other categories is not drawn. A fullyConfigdomainis the lower-level override: it wins over this, and is drawn exactly as given (rounded only byyConfig's ownrounding), without stretching to the chart'sbaseline.ySortfunctionCustom sort function for y-axis values.
zoombooleanDefaulttrueEnables pan/zoom with zoom-control buttons. On by default for every chart.
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-brushclasses. 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 one or more of the four built-in zoom-control icons (
zoomIn,zoomOut,zoomReset,zoomBrush), which otherwise render as inline SVGs. Each value is either an HTML string — used as the button's content in place of the built-in icon — or a mount function,(el: HTMLElement) => void | (() => void), called once with the button's reserved icon slot (a 12x12px element) so you can mount anything imperative into it: a React tree (createRoot(el).render(<Icon/>)), a Vue app, a canvas sprite, a brand<img>. Return a cleanup function from the mount function if there's teardown to do; it runs right before that slot is discarded — which happens whenever the whole button panel's markup regenerates (a.locale(...)change, azoomControlClassNamechange, or the brush toggle switching), not just once per chart.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.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.
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.