d3-jetpack is a set of nifty convenience wrappers that speed up your daily work with d3.js
(comic by Tom Gauld)
Usage
If you use NPM, npm install d3-jetpack. Otherwise, download the latest d3v4+jetpack.js.
Here's what's in the package:
# selection.append(selector) <>
Modifies append so it adds classes and ids.
selection.append("div.my-class");
selection.append("div.first-class.second-class");
selection.append("div#someId");
selection.append("div#someId.some-class");# selection.insert(selector) <>
Works with insert, too:
selection.insert("div.my-class");# selection.appendMany(selector, array) <>
Instead of making an empty selection, binding data to it, taking the enter selection and appending elements as separate steps:
selection.selectAll('div.my-class')
.data(myArray)
.enter()
.append('div.my-class');use appendMany:
selection.appendMany('div.my-class', myArray);# selection.at(name[, value]) <>
Works like d3v3's .attr. Passing an object to name sets multiple attributes, passing a string returns a single attribute and passing a string & second argument sets a single attribute.
To avoid having to use quotes around attributes and styles with hyphens when using the object notation, camelCase keys are hyphenated. Instead of:
selection
.attr('stroke-width', 10)
.attr('text-anchor', 'end')
.attr('font-weight', 600)or with d3-selection-multi:
selection.attrs({'stroke-width': 10, 'text-anchor': 'end', 'font-weight': 600})you can write:
selection.at({fontSize: 10, textAnchor: 'end', fontWeight: 600})With syntax highlighting on, it is a little easier to see the difference between keys and values when everything isn't a string. Plus there's less typing!
# selection.st(name[, value]) <>
Like at, but for style. Additionally, when a number is passed to a style that requires a unit of measure, like margin-top or font-size, px is automatically appended. Instead of
selection
.style('margin-top', height/2 + 'px')
.style('font-size', '40px')
.style('width', width - 80 + 'px')The + pxs can also be dropped:
selection.st({marginTop: height/2, fontSize: 40, width: width - 80})# d3.selectAppend(selector) <>
Selects the first element that matches the specified selector string or if no elements match the selector, it will append an element. This is often handy for elements which are required as part of the DOM hierachy, especially when making repeated calls to the same code. When appending it will also add id and classes, same as Jetpack's append
d3.selectAppend('ul.fruits')
.selectAll('li')
.data(data)Returns the parent of each element in the selection:
d3.selectAll('span')
.style('color', 'red')
.parent()
.style('background', 'yellow')This might mess with the joined data and/or return duplicate elements. Usually better to save a variable, but sometimes useful when working with nested html.
# selection.translate(xyPosition, [dim]) <>
How I hated writing .attr('transform', function(d) { return 'translate()'; }) a thousand times...
svg.append('g').translate([margin.left, margin.top]);
circle.translate(function(d) { return [x(d.date), y(d.value)]; });If you only want to set a single dimension you can tell translate by passing 0 (for x) or 1 (for y) as second argument:
x_ticks.translate(d3.f(x), 0);
y_ticks.translate(d3.f(y), 1);HTML is supported as well! translate uses style transforms with px units if the first element in the selection is HTML.
svg_selection.translate([40,20]); // will set attribute transform="translate(40, 20)"
html_selection.translate([40,20]); // will set style.transform = "translate(40px, 20px)"For multi-line SVG text
selection.append('text')
.tspans(function(d) {
return d.text.split('\n');
});
selection.append('text').tspans(['Multiple', 'lines'], 20);The optional second argument sets the line height (defaults to 15).
# d3.wordwrap(text, [lineWidth]) <>
Comes in handy with the tspans:
selection.append('text')
.tspans(function(d) {
return d3.wordwrap(text, 15); // break line after 15 characters
});d3.f takes a string|number and returns a function that takes an object and returns whatever property the string is named. This clears away much of verbose function(d){ return ... } syntax in ECMAScript 5:
x.domain(d3.extent(items, function(d){ return d.price; }));becomes
x.domain(d3.extent(items, d3.f('price'));d3.f even accepts multiple accessors and will execute them in the order of appearance. So for instance, let's say we have an array of polygon objects like this { points: [{x: 0, y: 3}, ...] } we can get the first y coordinates using:
var firstY = polygons.map(d3.f('points', 0, 'y'));Since we use this little function quite a lot, we usually set var ƒ = d3.f (type with [alt] + f on Macs). Also, in @1wheel's blog you can read more about the rationale behind ƒ.
These functions operate like d3.ascending / d3.descending but you can pass a key string or key function which will be used to specify the property by which to sort an array of objects.
var fruits = [{ name: "Apple", color: "green" }, { name: "Banana", color: "yellow" }];
fruits.sort(d3.ascendingKey('color'));# d3.timer(callback[, delay[, time[, namespace]]]) <>
d3.timer, d3.timeout and d3.interval all now take an optional namespace argument. Previous timers with the same namespace as a new timer are stopped.
Shorthand for d3.nest().key(key).entries(array). Returns an array of arrays, instead of a key/value pairs. The key property of each array is equal the value returned by the key function when it is called with element of the array.
d3.nest()
.key(d => d.year)
.entries(yields)
.forEach(function(d){
console.log('Count in ' + d.key + ': ' + d.values.length) })to
d3.nestBy(yields, d => d.year).forEach(function(d){
console.log('Count in ' + d.key + ': ' + d.length) })# d3.loadData(file1, file2, file3, ..., callback) <>
Takes any number of files paths and loads them with queue, d3.csv and d3.json. After all the files have loaded, calls the callback function with the first error (or null if there are none) as the first argument and an array of the loaded files as the second. Instead of:
d3.queue()
.defer(d3.csv, 'state-data.csv')
.defer(d3.tsv, 'county-data.tsv')
.defer(d3.json, 'us.json')
.awaitAll(function(err, res){
var states = res[0],
counties = res[1],
us = res[2]
})if your file types match their extensions, you can use:
d3.loadData('state-data.csv', 'county-data.tsv', 'us.json', function(err, res){
var states = res[0],
counties = res[1],
us = res[2]
})A useful short-hand method for +d3.format('.'+precision+'f')(x) also known as +x.toFixed(precision). Note that this code is fundamentally broken but still works fine 99% of the time.
d3.round(1.2345, 2) // 1.23Short for Math.max(min, Math.min(max, val)).
d3.clamp(0, -10, 200) // 0
d3.clamp(0, 110, 200) // 110
d3.clamp(0, 410, 200) // 200# d3.attachTooltip(selector) <>
Attaches a light weight tooltip that prints out all of an objects properties on click. No more > d3.select($0).datum()!
d3.select('body').selectAppend('div.tooltip')
circles.call(d3.attachTooltip)For formated tooltips, update the html of the tooltip on mouseover:
circles
.call(d3.attachTooltip)
.on('mouseover', function(d){
d3.select('.tooltip').html("Number of " + d.key + ": " + d.length) })Make sure to add a <div class='tooltip'></div> and that there's some tooltip css on the page:
.tooltip {
top: -1000px;
position: fixed;
padding: 10px;
background: rgba(255, 255, 255, .90);
border: 1px solid lightgray;
pointer-events: none;
}
.tooltip-hidden{
opacity: 0;
transition: all .3s;
transition-delay: .1s;
}
@media (max-width: 590px){
div.tooltip{
bottom: -1px;
width: calc(100%);
left: -1px !important;
right: -1px !important;
top: auto !important;
width: auto !important;
}
}# d3.conventions([options]) <>
d3.conventions([config]) creates an SVG with a G element translated to follow the margin convention. d3.conventions returns an object with the dimensions and location of the created element. Passing in a config object overrides the default dimensions.
To create this html:
<div id="graph">
<svg width=900 height=500>
<g transform="translate(20, 20)">
</svg>
</div>You could run this:
var sel = d3.select('#graph')
var totalWidth = 900
var totalHeight = 500
var {svg, margin, height, width} = d3.conventions({sel, totalHeight, totalWidth})
svg // d3 selection of G representing chart area
margin // padding around G, defaults to {top: 20, left: 20, height: 20, width: 20}
height // height of charting area (500 - 20 - 20 = 460 here)
weight // width of charting area (900 - 20 - 20 = 460 here)sel: d3.selection of the element the SVG was appended to. Defaults to d3.select("body"), but can be specified by passing in an object: d3.conventions({sel: d3.select("#graph-container")}) appends an SVG to #graph-container.
totalWidth/totalHeight: size of the SVG. By default uses the offsetWidth and offsetHeight of sel. d3.conventions({totalHeight: 500}) makes a responsive chart with a fixed height of 500.
margin: Individual keys override the defaults. d3.conventions({margins: {top: 50}}) sets the top margin to 50 and leaves the others at 20
width/height: inner charting area. If passed into conventions, totalWidth and totalHeight are set to the extent of the charting area plus the margins. d3.conventions({width: 200, height: 200, margin: {top: 50}}) creates a square charting area with extra top margin.
layers: d3.conventions can also create multiple canvas and div elements. d3.conventions({layers: 'sdc'}) makes an SVG, DIV and canvas ctx with the same margin and size. Layers are positioned absolutely on top of each other in the order listed in the layer string. To create an SVG with two canvas elements on top:
var {layers: [svg, bg_ctx, fg_ctx]} = d3.conventions({layers: 'scc'})layers defaults to 's', creating a single SVG.
Most charts use two linear scales and axii. d3.conventions returns some functions to get you started, but feel free to use something else!
x: scaleLinear().range([0, width]). To use a different scale: d3.conventions({x: d3.scaleSqrt()}).
y: scaleLinear().range([height, 0]).
xAxis: axisBottom().scale(x).
yAxis: axisLeft().scale(y).
# d3.drawAxis({svg, xAxis, yAxis, height}) <>
Appends an xAxis aligned to the bottom of svg and a yAxis aligned to the left. You can pass the output of conventions directly to drawAxis, but make sure to set an x and y domain first!
var c = d3.conventions()
c.x.domain([1990, 2015])
c.y.domain(d3.extent(data, d => d.cost))
d3.drawAxis(c)
Essential jetpack
If you think jetpack adds too much to your build, try starting with the essential jetpack and adding features as you need them.
// essentials (insert, append, appendMany etc)
import {f} from 'd3-jetpack/essentials';
// get some extra stuff
import attachTooltip from 'd3-jetpack/src/attachTooltip'