d3plus-plot

A reusable javascript x/y plot built on D3.

Installing

If using npm, npm install d3plus-plot. Otherwise, you can download the latest release from GitHub or load from a CDN.

import modules from "d3plus-plot";

d3plus-plot 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-plot@1"></script>
<script>
  console.log(d3plus);
</script>

Examples

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. :beers:

API Reference

• AreaPlot
• BarChart
• BoxWhisker
• BumpChart
• LinePlot
• Plot
• Radar
• StackedArea

AreaPlot <>

This is a global class, and extends all of the methods and functionality of Plot.

# new AreaPlot()

Creates an area plot based on an array of data.

the equivalent of calling:

new d3plus.Plot()
  .baseline(0)
  .discrete("x")
  .shape("Area")

BarChart <>

This is a global class, and extends all of the methods and functionality of Plot.

# new BarChart()

Creates a bar chart based on an array of data.

the equivalent of calling:

new d3plus.Plot()
  .baseline(0)
  .discrete("x")
  .shape("Bar")

BoxWhisker <>

This is a global class, and extends all of the methods and functionality of Plot.

# new BoxWhisker()

Creates a simple box and whisker based on an array of data.

the equivalent of calling:

new d3plus.Plot()
  .discrete("x")
  .shape("Box")

BumpChart <>

This is a global class, and extends all of the methods and functionality of Plot.

# new BumpChart()

Creates a bump chart based on an array of data.

the equivalent of calling:

new d3plus.Plot()
  .discrete("x")
  .shape("Line")
  .x("x")
  .y2(d => this._y(d))
  .yConfig({
    tickFormat: val => {
      const data = this._formattedData;
      const xDomain = this._xDomain;
      const startData = data.filter(d => d.x === xDomain[0]);
      const d = startData.find(d => d.y === val);
      return this._drawLabel(d, d.i);
     }
   })
  .y2Config({
    tickFormat: val => {
      const data = this._formattedData;
      const xDomain = this._xDomain;
      const endData = data.filter(d => d.x === xDomain[xDomain.length - 1]);
      const d = endData.find(d => d.y === val);
      return this._drawLabel(d, d.i);
     }
   })
  .ySort((a, b) => b.y - a.y)
  .y2Sort((a, b) => b.y - a.y)

LinePlot <>

This is a global class, and extends all of the methods and functionality of Plot.

# new LinePlot()

Creates a line plot based on an array of data.

the equivalent of calling:

new d3plus.Plot()
  .discrete("x")
  .shape("Line")

Plot <>

This is a global class, and extends all of the methods and functionality of Viz.

• Plot ⇐ Viz
  • new Plot()
  • .annotations(annotations) ↩︎
  • .axisPersist([value]) ↩︎
  • .backgroundConfig([value]) ↩︎
  • .barPadding(value) ↩︎
  • .baseline(value) ↩︎
  • .buffer([value]) ↩︎
  • .confidence(value) ↩︎
  • .confidenceConfig([value]) ↩︎
  • .discrete(value) ↩︎
  • .discreteCutoff(value) ↩︎
  • .groupPadding([value]) ↩︎
  • .labelConnectorConfig([value]) ↩︎
  • .lineLabels([value]) ↩︎
  • .lineMarkerConfig(value) ↩︎
  • .lineMarkers([value]) ↩︎
  • .shapeSort(value) ↩︎
  • .size(value) ↩︎
  • .sizeMax(value) ↩︎
  • .sizeMin(value) ↩︎
  • .sizeScale(value) ↩︎
  • .stacked(value) ↩︎
  • .stackOffset(value) ↩︎
  • .stackOrder(value) ↩︎
  • .x(value) ↩︎
  • .x2(value) ↩︎
  • .xConfig(value) ↩︎
  • .xCutoff(value) ↩︎
  • .x2Config(value) ↩︎
  • .xDomain(value) ↩︎
  • .x2Domain(value) ↩︎
  • .xSort(value) ↩︎
  • .x2Sort(value) ↩︎
  • .y(value) ↩︎
  • .y2(value) ↩︎
  • .yConfig(value) ↩︎
  • .yCutoff(value) ↩︎
  • .y2Config(value) ↩︎
  • .yDomain(value) ↩︎
  • .y2Domain(value) ↩︎
  • .ySort(value) ↩︎
  • .y2Sort(value) ↩︎

# new Plot()

Creates an x/y plot based on an array of data.

# Plot.annotations(annotations) <>

Allows 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.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.axisPersist([value]) <>

Determines 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 true to make the axes stay consistent when the timeline changes).

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.backgroundConfig([value]) <>

A d3plus-shape configuration Object used for styling the background rectangle of the inner x/y plot (behind all of the shapes and gridlines).

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.barPadding(value) <>

Sets the pixel space between each bar in a group of bars.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.baseline(value) <>

Sets the baseline for the x/y plot. If value is not specified, returns the current baseline.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.buffer([value]) <>

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 true or false to toggle the behavior for all shape types, or a keyed Object for each shape type (ie. {Bar: false, Circle: true, Line: false}).

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.confidence(value) <>

Sets the confidence to the specified array of lower and upper bounds.

This is a static method of Plot, and is chainable with other methods of this Class. Can be called with accessor functions or static keys:

       var data = {id: "alpha", value: 10, lci: 9, hci: 11};
       ...
       // Accessor functions
       .confidence([function(d) { return d.lci }, function(d) { return d.hci }])

       // Or static keys
       .confidence(["lci", "hci"])

# Plot.confidenceConfig([value]) <>

If value is specified, sets the config method for each shape rendered as a confidence interval and returns the current class instance.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.discrete(value) <>

Sets the discrete axis to the specified string. If value is not specified, returns the current discrete axis.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.discreteCutoff(value) <>

When 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 0 to disable the behavior entirely.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.groupPadding([value]) <>

Sets the pixel space between groups of bars.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.labelConnectorConfig([value]) <>

The d3plus-shape config used on the Line shapes created to connect lineLabels to the end of their associated Line path.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.lineLabels([value]) <>

Draws labels on the right side of any Line shapes that are drawn on the plot.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.lineMarkerConfig(value) <>

Shape config for the Circle shapes drawn by the lineMarkers method.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.lineMarkers([value]) <>

Draws circle markers on each vertex of a Line.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.shapeSort(value) <>

A JavaScript sort comparator function that receives each shape Class (ie. "Circle", "Line", etc) as it's comparator arguments. Shapes are drawn in groups based on their type, so you are defining the layering order for all shapes of said type.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.size(value) <>

Sets the size of bubbles to the given Number, data key, or function.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.sizeMax(value) <>

Sets the size scale maximum to the specified number.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.sizeMin(value) <>

Sets the size scale minimum to the specified number.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.sizeScale(value) <>

Sets the size scale to the specified string.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.stacked(value) <>

If value is specified, toggles shape stacking. If value is not specified, returns the current stack value.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.stackOffset(value) <>

Sets the stack offset. If value is not specified, returns the current stack offset function.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.stackOrder(value) <>

Sets the stack order. If value is not specified, returns the current stack order function.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.x(value) <>

Sets the x accessor to the specified function or number. If value is not specified, returns the current x accessor.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.x2(value) <>

Sets the x2 accessor to the specified function or number. If value is not specified, returns the current x2 accessor.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.xConfig(value) <>

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.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.xCutoff(value) <>

When the width of the chart is less than or equal to this pixel value, and the x-axis is not the discrete axis, it will not be shown. This helps produce slick sparklines. Set this value to 0 to disable the behavior entirely.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.x2Config(value) <>

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.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.xDomain(value) <>

Sets the x domain to the specified array. If value is not specified, returns the current x domain. Additionally, if either value of the array is undefined, it will be calculated from the data.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.x2Domain(value) <>

Sets the x2 domain to the specified array. If value is not specified, returns the current x2 domain. Additionally, if either value of the array is undefined, it will be calculated from the data.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.xSort(value) <>

Defines a custom sorting comparitor function to be used for discrete x axes.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.x2Sort(value) <>

Defines a custom sorting comparitor function to be used for discrete x2 axes.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.y(value) <>

Sets the y accessor to the specified function or number. If value is not specified, returns the current y accessor.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.y2(value) <>

Sets the y2 accessor to the specified function or number. If value is not specified, returns the current y2 accessor.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.yConfig(value) <>

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.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.yCutoff(value) <>

When the height of the chart is less than or equal to this pixel value, and the y-axis is not the discrete axis, it will not be shown. This helps produce slick sparklines. Set this value to 0 to disable the behavior entirely.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.y2Config(value) <>

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.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.yDomain(value) <>

Sets the y domain to the specified array. If value is not specified, returns the current y domain. Additionally, if either value of the array is undefined, it will be calculated from the data.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.y2Domain(value) <>

Sets the y2 domain to the specified array. If value is not specified, returns the current y2 domain. Additionally, if either value of the array is undefined, it will be calculated from the data.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.ySort(value) <>

Defines a custom sorting comparitor function to be used for discrete y axes.

This is a static method of Plot, and is chainable with other methods of this Class.

# Plot.y2Sort(value) <>

Defines a custom sorting comparitor function to be used for discrete y2 axes.

This is a static method of Plot, and is chainable with other methods of this Class.

Radar <>

This is a global class, and extends all of the methods and functionality of Viz.

• Radar ⇐ Viz
  • new Radar()
  • .axisConfig(value) ↩︎
  • .metric(value) ↩︎
  • .outerPadding([value]) ↩︎
  • .value(value)

# new Radar()

Creates a radar visualization based on an array of data.

# Radar.axisConfig(value) <>

Sets the config method used for the radial spokes, circles, and labels.

This is a static method of Radar, and is chainable with other methods of this Class.

# Radar.metric(value) <>

Defines the value used as axis. If value is specified, sets the accessor to the specified metric function. If value is not specified, returns the current metric accessor.

This is a static method of Radar, and is chainable with other methods of this Class.

# Radar.outerPadding([value]) <>

Determines how much pixel spaces to give the outer labels.

This is a static method of Radar, and is chainable with other methods of this Class.

# Radar.value(value) <>

If value is specified, sets the value accessor to the specified function or number and returns the current class instance. If value is not specified, returns the current value accessor.

This is a static method of Radar.

function value(d) {
  return d.value;
}

StackedArea <>

This is a global class, and extends all of the methods and functionality of Area.

# new StackedArea()

Creates a stacked area plot based on an array of data.

the equivalent of calling:

new d3plus.AreaPlot()
  .stacked(true)

Documentation generated on Thu, 24 Oct 2024 14:16:56 GMT