Skip to content

A basic wrapper for d3-scale and d3-axis, mainly used as a dependency for our chart and slider

License

Notifications You must be signed in to change notification settings

TimeMagazineLabs/d3axis

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

9 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

d3axis

v0.0.2

A basic wrapper for d3-scale and d3-axis, mainly used as a dependency for our chart and slider

Installation

npm install d3axis
import { d3axis } from 'd3axis'

Or, if you want to use it independently, you download dist/d3axis-min.js and include it like normal:

<script src='d3axis-min.js'></script>

Philosophy

This is not a wrapper. It's just a way to save you time coding a D3 scale-axis pairing from scratch. The object it returns exposes both the scale and the axis directly, as if you had manually declared them. Thus, you can do anything D3 can do by directly modifying the scale or axis objects, both of which are directly exposed in the d3axis object.

There are not a great deal of convenience methods since you can do anything you want yourself. Even sophisticated Javascript "easy chart" libraries generally don't allow the user to implement every possible, unforeseeable feature. Instead, this module, as well as the related d3slider and d3charts that use it, is just a container that saves you a lot of copying and pasting from the previous time you made an axis.

Usage

d3axis doesn't create an svg for you since it's typically a dependency of a module with an existing svg. To declare a new axis, you need to pass an 'svg' or 'g', along with some optional settings. The first argument can be an HTML element or a selector.

const xAxis = d3axis(svg, {
	direction: 'x',
	margin: { left: 35, top: 50 },
	domain: [1, 10]
});

const yAxis = d3axis('#svgID', { 
	direction: 'y', 
	orientation: 'right',
	type: "log",
	base: 2,
	domain: [2, 128]
});

Options

All optional, as the name might suggest.

property description default options
direction horizontal or vertical 'x' 'x', 'y'
length width or height of the scale, including margins container width or height number
margin spacing on sides of axis (as object) x: { left: 20, right: 20, top: 35, bottom: 30 }
y: { left: 45, right: 30, top: 20, bottom: 30 }
object of numbers
type type of scale linear 'linear', 'time', 'ordinal', 'log'
domain domain values [0, 1] [min, max] of relevant data type or list for ordinal
orientation Which side the axis appears 'left' or 'bottom' 'left', 'right' (x), 'top', 'bottom' (y)
rules Make the tick lines span the chart true true, false or omitted
tickLength Tick length. Overridden by rules 10 number
id DOM id null String
label Axis label null String
label_offset Distance from label to numbers 25 (bottom, right), -20 (top), -25 (left)

Specially exposed d3 values

While you can manipulate any part of the scale or axis, since both are exposed, three commonly used axis specifications are available in the initial options:

property description
tickFormat Pass-through to d3.axis.tickFormat
tickValues Pass-through to d3.axis.tickValues
ticks Pass-through to d3.axis.ticks

Properties and Methods

The object that d3axis--let's called it myAxis--return a few core properties and a handful of methods for when you need to update it:

property description
settings The object will all the options above, whether you declared them or used the default.
scale The core d3-scale object. Do anything you like with it.
axis The core d3-axis object. Likewise.
method description
.update(ms) Reinitializes the axis with an optional transition in milliseconds. Call this any time you modify the scale or axis.
.resize() Dynamically resize the range if the size of the container has changed. This can be attached to an window.resize event listener
.setDomain([min,max], ms) A convenience method for resetting the domain. You could do this by hand.

In brief, any time you want to modify the scale or the axis, you need to call myAxis.update(duration). For example, the equivalent of myAxis.setDomain([0,100], 2000) is:

myAxis.scale.domain([0, 100]);
myAxis.update(2000);

Dynamic resizing

This scale does not automatically rescale if the container size changes since that is often triggered by a parent application. But you may call .resize() any time. For example, in demo.html, the <svg> elements are sized by percentage, and if you narrow the window size you'll see the scales adjust thanks to this listener:

window.onresize = function() {
	xScaleBottom.resize();
	xScaleTop.resize();
	yScaleLeft.resize();
	yScaleRight.resize();
};

About

A basic wrapper for d3-scale and d3-axis, mainly used as a dependency for our chart and slider

Resources

License

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published