D3 Convention encoded as an npm package
JavaScript HTML
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.



D3 Margin Convention encoded as an npm package. Idea "forked" from 1wheel/d3-starterkit


d3-convention depends on d3 as a peer dependency

npm install d3 d3-convention


var c = require('d3-convention')()

      width: c.x(0.5), // 50% wide
      height: c.y(0.5), // 50% high

      x: c.x(0.25), // Center horizontally
      y: c.y(0.75) // Center vertically
    .style('fill', 'steelblue')


All options have sane defaults, however d3Convention([opts]) accepts:

var c = d3Convention({
  margin: Number || {top: Number, right: Number, bottom: Number, left: Number},
  width: Number,
  height: Number,

  parent: DOMElement || String || d3.select,
  svg: SVGElement || String || d3.select // preferably SVGSVGElement

It will mutate the originally passed opts Object, with these properties:

  • c.margin is an Object with the properties {top, right, bottom, left} either the originally passed opts.margin object, an object expanded from the Number passed or the default {top: 20, right: 10, bottom: 20, left: 10}
  • c.width is the "scene" width excluding margin on the left and right side. Defaults to 960 - margin.left - margin.right = 940
  • c.height, under the same constraints as c.width. Defaults to 460
  • c.outerWidth the width of the SVG element. Calculated from c.width + c.margin.left + c.margin.right. Default resolves to 960
  • c.outerHeight the actual height of the "drawing scene". Calculated from c.height + c.margin.top + c.margin.bottom. Default resolves to 500
  • c.parent is either the passed opts.parent or a D3 selection with the body element. This is where the c.svg element is inserted, unless opts.svg is passed, in which case this property is ignored
  • c.svg is a newly inserted <g> element which is translated. We will try to set the width and height attrs of this, as well as appending a <g> element which is translated. However specifying opts.svg allows you to some of your SVG markup and just insert the conventions in a child node, eg. if you hardcode something like a legend
  • c.x is a d3.scale.linear scale that maps [0, 1] -> [0, opts.innerWidht]
  • c.y is a flipped d3.scale.linear scale so that 0 is at the bottom of the scene. It maps [0, 1] -> [opts.innerHeight, 0] (note the upside-downness)
  margin: {top: Number, right: Number, bottom: Number, left: Number},
  width: opts.width || 960,
  height: opts.height || 500,

  innerWidth: Number,
  innerHeight: Number,

  parent: d3.select(opts.parent || HTMLBodyElement),
  svg: s3.select(SVGGElement),

  x: d3.scale.linear,
  y: d3.scale.linear

Notable Differences

d3-convention was inspired by Block #3019563 and 1wheel/d3-starterkit.

It differs from d3-starterkit in several ways:

  • margin is subtracted, where d3-starterkit adds margin to your specified width and height
  • This does not return the same breadth of scales by default
  • This does not return any axis
  • parentSel is parent. This lets you pass whatever d3.select accepts, it being Element, selector or an existing d3.selection