Abstract ES6 class that drives d3plus visualizations.
If using npm, npm install d3plus-viz. Otherwise, you can download the latest release from GitHub or load from a CDN.
import modules from "d3plus-viz";d3plus-viz can be loaded as a standalone library or bundled as part of D3plus. ES modules, AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3plus global is exported:
<script src="https://cdn.jsdelivr.net/npm/d3plus-viz@1"></script>
<script>
console.log(d3plus);
</script>Live examples can be found on d3plus.org, which includes a collection of example visualizations using d3plus-react. These examples are powered by the d3plus-storybook repo, and PRs are always welcome. 🍻
- isData - Adds the provided value to the internal queue to be loaded, if necessary. This is used internally in new d3plus visualizations that fold in additional data sources, like the nodes and links of Network or the topojson of Geomap.
- dataConcat - Reduce and concat all the elements included in arrayOfArrays if they are arrays. If it is a JSON object try to concat the array under given key data. If the key doesn't exists in object item, a warning message is lauched to the console. You need to implement DataFormat callback to concat the arrays manually.
- dataFold - Given a JSON object where the data values and headers have been split into separate key lookups, this function will combine the data values with the headers and returns one large array of objects.
- isData - Returns true/false whether the argument provided to the function should be loaded using an internal XHR request. Valid data can either be a string URL or an Object with "url" and "headers" keys.
- dataLoad - Loads data from a filepath or URL, converts it to a valid JSON object, and returns it to a callback function.
- defaultPadding - Default padding logic that will return false if the screen is less than 600 pixels wide.
- listify - Turns an array of values into a list string.
- _thresholdFunction - Applies the threshold algorithm according to the type of chart used.
Viz <>
This is a global class, and extends all of the methods and functionality of BaseClass.
- Viz ⇐
BaseClass- new Viz()
- .render([callback]) ↩︎
- .active([value]) ↩︎
- .aggs([value]) ↩︎
- .ariaHidden([value]) ↩︎
- .attribution(value) ↩︎
- .attributionStyle([value]) ↩︎
- .backConfig([value]) ↩︎
- .cache([value]) ↩︎
- .color([value]) ↩︎
- .colorScale([value]) ↩︎
- .colorScaleConfig([value]) ↩︎
- .colorScalePadding([value]) ↩︎
- .colorScalePosition([value]) ↩︎
- .colorScaleMaxSize([value]) ↩︎
- .data(data, [formatter]) ↩︎
- .dataCutoff([value]) ↩︎
- .depth([value]) ↩︎
- .detectResize(value) ↩︎
- .detectResizeDelay(value) ↩︎
- .detectVisible(value) ↩︎
- .detectVisibleInterval(value) ↩︎
- .discrete([value]) ↩︎
- .downloadButton([value]) ↩︎
- .downloadConfig([value]) ↩︎
- .downloadPosition([value]) ↩︎
- .duration([ms]) ↩︎
- .filter([value]) ↩︎
- .groupBy([value]) ↩︎
- .height([value]) ↩︎
- .hiddenColor([value]) ↩︎
- .hiddenOpacity([value]) ↩︎
- .hover([value]) ↩︎
- .label([value]) ↩︎
- .legend([value]) ↩︎
- .legendConfig([value]) ↩︎
- .legendFilterInvert([value]) ↩︎
- .legendPadding([value]) ↩︎
- .legendPosition([value]) ↩︎
- .legendSort(value) ↩︎
- .legendTooltip([value]) ↩︎
- .loadingHTML([value]) ↩︎
- .loadingMessage([value]) ↩︎
- .messageMask([value]) ↩︎
- .messageStyle([value]) ↩︎
- .noDataHTML([value]) ↩︎
- .noDataMessage([value]) ↩︎
- .resizeContainer(selector) ↩︎
- .scrollContainer(selector) ↩︎
- .select([selector]) ↩︎
- .shape([value]) ↩︎
- .shapeConfig([value]) ↩︎
- .subtitle([value]) ↩︎
- .subtitleConfig([value]) ↩︎
- .subtitlePadding([value]) ↩︎
- .svgDesc([value]) ↩︎
- .svgTitle([value]) ↩︎
- .threshold([value]) ↩︎
- .thresholdKey([value]) ↩︎
- .thresholdName([value]) ↩︎
- .time([value]) ↩︎
- .timeFilter([value]) ↩︎
- .timeline([value]) ↩︎
- .timelineConfig([value]) ↩︎
- .timelineDefault([value]) ↩︎
- .timelinePadding([value]) ↩︎
- .title([value]) ↩︎
- .titleConfig([value]) ↩︎
- .titlePadding([value]) ↩︎
- .tooltip([value]) ↩︎
- .tooltipConfig([value]) ↩︎
- .total([value]) ↩︎
- .totalConfig([value]) ↩︎
- .totalFormat(value) ↩︎
- .totalPadding([value]) ↩︎
- .width([value]) ↩︎
- .zoom(value) ↩︎
- .zoomBrushHandleSize(value) ↩︎
- .zoomBrushHandleStyle(value) ↩︎
- .zoomBrushSelectionStyle(value) ↩︎
- .zoomControlStyle(value) ↩︎
- .zoomControlStyleActive(value) ↩︎
- .zoomControlStyleHover(value) ↩︎
- .zoomFactor(value) ↩︎
- .zoomMax(value) ↩︎
- .zoomPan(value) ↩︎
- .zoomPadding(value) ↩︎
- .zoomScroll([value]) ↩︎
# new Viz()
Creates an x/y plot based on an array of data. If data is specified, immediately draws the tree map based on the specified array and returns the current class instance. If data is not specified on instantiation, it can be passed/updated after instantiation using the data method. See this example for help getting started using the treemap generator.
Draws the visualization given the specified configuration.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the active method to the specified function and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the aggregation method for each key in the object and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
Sets the "aria-hidden" attribute of the containing SVG element. The default value is "false", but it you need to hide the SVG from screen readers set this property to "true".
This is a static method of Viz, and is chainable with other methods of this Class.
Sets 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).
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.attributionStyle([value]) <>
If value is specified, sets the config method for the back button and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the config method for the back button and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
Enables a lru cache that stores up to 5 previously loaded files/URLs. Helpful when constantly writing over the data array with a URL in the render function of a react component.
This is a static method of Viz, and is chainable with other methods of this Class.
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.
This is a static method of Viz, and is chainable with other methods of this Class.
Defines 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.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.colorScaleConfig([value]) <>
A pass-through to the config method of ColorScale.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.colorScalePadding([value]) <>
Tells 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.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.colorScalePosition([value]) <>
Defines which side of the visualization to anchor the color scale. Acceptable values are "top", "bottom", "left", "right", and false. A false value will cause the color scale to not be displayed, but will still color shapes based on the scale.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.colorScaleMaxSize([value]) <>
Sets the maximum pixel size for drawing the color scale: width for horizontal scales and height for vertical scales.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.data(data, [formatter]) <>
Sets the primary data array to be used when drawing the visualization. The value passed should be an Array of objects or a String representing a filepath or URL to be loaded. The following filetypes are supported: csv, tsv, txt, and json.
If your data URL needs specific headers to be set, an Object with "url" and "headers" keys may also be passed.
Additionally, a custom formatting function can be passed as a second argument to this method. This custom function will be passed the data that has been loaded, as long as there are no errors. This function should return the final array of obejcts to be used as the primary data array. For example, some JSON APIs return the headers split from the data values to save bandwidth. These would need be joined using a custom formatter.
If you would like to specify certain configuration options based on the yet-to-be-loaded data, you can also return a full config object from the data formatter (including the new data array as a key in the object).
If data is not specified, this method returns the current primary data array, which defaults to an empty array ([]);
This is a static method of Viz, and is chainable with other methods of this Class.
| Param | Type | Description |
|---|---|---|
| data | Array | String |
= [] |
| [formatter] | function |
If the number of visible data points exceeds this number, the default hover behavior will be disabled (helpful for very large visualizations bogging down the DOM with opacity updates).
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the depth to the specified number and returns the current class instance. The value should correspond with an index in the groupBy array.
This is a static method of Viz, and is chainable with other methods of this Class.
If 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 the window.onresize event and adjust it's dimensions accordingly.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.detectResizeDelay(value) <>
When resizing the browser window, this is the millisecond delay to trigger the resize event.
This is a static method of Viz, and is chainable with other methods of this Class.
Toggles 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.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.detectVisibleInterval(value) <>
The interval, in milliseconds, for checking if the visualization is visible on the page.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the discrete accessor to the specified method name (usually an axis) and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.downloadButton([value]) <>
Shows a button that allows for downloading the current visualization.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.downloadConfig([value]) <>
Sets specific options of the saveElement function used when downloading the visualization.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.downloadPosition([value]) <>
Defines which control group to add the download button into.
This is a static method of Viz, and is chainable with other methods of this Class.
If ms is specified, sets the animation duration to the specified number and returns the current class instance. If ms is not specified, returns the current animation duration.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the filter to the specified function and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the group accessor(s) to the specified string, function, or array of values and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
function value(d) {
return d.id;
}If value is specified, sets the overall height to the specified number and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
Defines the color used for legend shapes when the corresponding grouping is hidden from display (by clicking on the legend).
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.hiddenOpacity([value]) <>
Defines the opacity used for legend labels when the corresponding grouping is hidden from display (by clicking on the legend).
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the hover method to the specified function and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the label accessor to the specified function or string and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, toggles the legend based on the specified boolean and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.legendConfig([value]) <>
If value is specified, the object is passed to the legend's config method.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.legendFilterInvert([value]) <>
Defines 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 with solo that category and shift+clicking will hide that category.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.legendPadding([value]) <>
Tells 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.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.legendPosition([value]) <>
Defines which side of the visualization to anchor the legend. Expected values are "top", "bottom", "left", and "right".
This is a static method of Viz, and is chainable with other methods of this Class.
A JavaScript sort comparator function used to sort the legend.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.legendTooltip([value]) <>
If value is specified, sets the config method for the legend tooltip and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
Sets the inner HTML of the status message that is 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.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.loadingMessage([value]) <>
Toggles the visibility of the status message that is displayed when loading AJAX requests and displaying errors.
This is a static method of Viz, and is chainable with other methods of this Class.
Sets the color of the mask used underneath the status message that is displayed when loading AJAX requests and displaying errors. Additionally, false will turn off the mask completely.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.messageStyle([value]) <>
Defines the CSS style properties for the status message that is displayed when loading AJAX requests and displaying errors.
This is a static method of Viz, and is chainable with other methods of this Class.
Sets the inner HTML of the status message that is 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.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.noDataMessage([value]) <>
Toggles the visibility of the status message that is displayed when no data is supplied to the visualization.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.resizeContainer(selector) <>
If using resize detection, this method allow a custom override of the element to which the resize detection function gets attached.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.scrollContainer(selector) <>
If using scroll or visibility detection, this method allow a custom override of the element to which the scroll detection function gets attached.
This is a static method of Viz, and is chainable with other methods of this Class.
If selector is specified, sets the SVG container element to the specified d3 selector or DOM element and returns the current class instance. If selector is not specified, returns the current SVG container element, which is undefined by default.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the shape accessor to the specified function or number and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the config method for each shape and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the subtitle accessor to the specified function or string and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.subtitleConfig([value]) <>
If value is specified, sets the config method for the subtitle and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.subtitlePadding([value]) <>
Tells 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.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the description accessor to the specified string and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the title accessor to the specified string and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the threshold for buckets to the specified function or string, and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.thresholdKey([value]) <>
If value is specified, sets the accesor for the value used in the threshold algorithm, and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.thresholdName([value]) <>
If value is specified, sets the label for the bucket item, and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the time accessor to the specified function or string and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the time filter to the specified function and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, toggles the timeline based on the specified boolean and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.timelineConfig([value]) <>
If value is specified, sets the config method for the timeline and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.timelineDefault([value]) <>
Sets the starting time or range for the timeline. The value provided can either be a single Date/String, or an Array of 2 values representing the min and max.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.timelinePadding([value]) <>
Tells 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.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the title accessor to the specified function or string and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the config method for the title and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.titlePadding([value]) <>
Tells 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.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, toggles the tooltip based on the specified boolean and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.tooltipConfig([value]) <>
If value is specified, sets the config method for the tooltip and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the total accessor to the specified function or string and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the config method for the total and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
Formatter function for the value in the total bar.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.totalPadding([value]) <>
Tells 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.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the overallwidth to the specified number and returns the current class instance.
This is a static method of Viz, and is chainable with other methods of this Class.
Toggles the ability to zoom/pan the visualization. Certain parameters for zooming are required to be hooked up on a visualization by visualization basis.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.zoomBrushHandleSize(value) <>
The pixel stroke-width of the zoom brush area.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.zoomBrushHandleStyle(value) <>
An object containing CSS key/value pairs that is used to style the outer handle area of the zoom brush. Passing false will remove all default styling.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.zoomBrushSelectionStyle(value) <>
An object containing CSS key/value pairs that is used to style the inner selection area of the zoom brush. Passing false will remove all default styling.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.zoomControlStyle(value) <>
An object containing CSS key/value pairs that is used to style each zoom control button (.zoom-in, .zoom-out, .zoom-reset, and .zoom-brush). Passing false will remove all default styling.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.zoomControlStyleActive(value) <>
An 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). Passing false will remove all default styling.
This is a static method of Viz, and is chainable with other methods of this Class.
# Viz.zoomControlStyleHover(value) <>
An 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). Passing false will remove all default styling.
This is a static method of Viz, and is chainable with other methods of this Class.
The multiplier that is used in with the control buttons when zooming in and out.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, sets the max zoom scale to the specified number and returns the current class instance. If value is not specified, returns the current max zoom scale.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, toggles panning to the specified boolean and returns the current class instance. If value is not specified, returns the current panning value.
This is a static method of Viz, and is chainable with other methods of this Class.
A pixel value to be used to pad all sides of a zoomed area.
This is a static method of Viz, and is chainable with other methods of this Class.
If value is specified, toggles scroll zooming to the specified boolean and returns the current class instance. If value is not specified, returns the current scroll zooming value.
This is a static method of Viz, and is chainable with other methods of this Class.
d3plus.isData(data, [data], data) <>
Adds the provided value to the internal queue to be loaded, if necessary. This is used internally in new d3plus visualizations that fold in additional data sources, like the nodes and links of Network or the topojson of Geomap.
This is a global function.
| Param | Type | Description |
|---|---|---|
| data | Array | String | Object |
The data to be loaded |
| [data] | function |
An optional data formatter/callback |
| data | String |
The internal Viz method to be modified |
d3plus.dataConcat(arrayOfArray, [data]) <>
Reduce and concat all the elements included in arrayOfArrays if they are arrays. If it is a JSON object try to concat the array under given key data. If the key doesn't exists in object item, a warning message is lauched to the console. You need to implement DataFormat callback to concat the arrays manually.
This is a global function.
| Param | Type | Default | Description |
|---|---|---|---|
| arrayOfArray | Array |
Array of elements | |
| [data] | String |
"data" |
The key used for the flat data array if exists inside of the JSON object. |
d3plus.dataFold(json, [data], [headers]) <>
Given a JSON object where the data values and headers have been split into separate key lookups, this function will combine the data values with the headers and returns one large array of objects.
This is a global function.
| Param | Type | Default | Description |
|---|---|---|---|
| json | Object |
A JSON data Object with data and headers keys. |
|
| [data] | String |
"data" |
The key used for the flat data array inside of the JSON object. |
| [headers] | String |
"headers" |
The key used for the flat headers array inside of the JSON object. |
d3plus.isData(dataItem) <>
Returns true/false whether the argument provided to the function should be loaded using an internal XHR request. Valid data can either be a string URL or an Object with "url" and "headers" keys.
This is a global function.
d3plus.dataLoad(path, [formatter], [key], [callback]) <>
Loads data from a filepath or URL, converts it to a valid JSON object, and returns it to a callback function.
This is a global function.
| Param | Type | Description |
|---|---|---|
| path | Array | String |
The path to the file or url to be loaded. Also support array of paths strings. If an Array of objects is passed, the xhr request logic is skipped. |
| [formatter] | function |
An optional formatter function that is run on the loaded data. |
| [key] | String |
The key in the this context to save the resulting data to. |
| [callback] | function |
A function that is called when the final data is loaded. It is passed 2 variables, any error present and the data loaded. |
d3plus.defaultPadding() <>
Default padding logic that will return false if the screen is less than 600 pixels wide.
This is a global function.
d3plus.listify() <>
Turns an array of values into a list string.
This is a global function.
d3plus._thresholdFunction(data) <>
Applies the threshold algorithm according to the type of chart used.
This is a global function.