SVG Axes

Wiki ▸ API Reference ▸ SVG ▸ SVG Axes

D3’s axis component displays reference lines for scales automatically. This lets you focus on displaying the data, while the axis component takes care of the tedious task of drawing axes and labeled ticks.

Axis

The axis component is designed to work with any of D3’s quantitative scales.

# d3.svg.axis()

Create a new default axis.

# axis(selection)

Apply the axis to a selection or transition. The selection must contain an SVG or G element. For example:

d3.select("body").append("svg")
    .attr("class", "axis")
    .attr("width", 1440)
    .attr("height", 30)
  .append("g")
    .attr("transform", "translate(0,30)")
    .call(axis);

# axis.scale([scale])

Get or set the associated scale. If scale is specified, sets the scale and returns the axis. If scale is not specified, returns the current scale which defaults to a linear scale.

# axis.orient([orientation])

Get or set the axis orientation. If orientation is specified, sets the axis orientation and returns the axis. If orientation is not specified, returns the current orientation, which defaults to "bottom". Valid values are "top", "bottom", "left" and "right". For a vertical axis, specify "left" or "right"; for a horizontal axis, specify "top" or "bottom".

# axis.ticks([arguments…])

Get or set the arguments that are passed to the underlying scale’s tick function. The specified arguments are passed to scale.ticks to compute the tick values. For quantitative scales, specify the desired tick count such as axis.ticks(20). For time scales, you can pass in a count or a function, such as axis.ticks(d3.time.minutes, 15).

The arguments are also passed to the scale’s tickFormat method to generate the default tick format. Thus, for log scales, you might specify both a count and a tick format function.

# axis.tickValues([values])

Get or set the explicit tick values. If the array values is specified, the values are used to generate ticks rather than using the scale's tick generator. If values is null, clears any previously-set explicit tick values, reverting back to the scale's tick generator. If values is not specified, returns the currently-set tick values, if any. For example, to generate ticks at specific values:

var xAxis = d3.svg.axis()
    .scale(x)
    .tickValues([1, 2, 3, 5, 8, 13, 21]);

The explicit tick values take precedent over the tick arguments set by axis.ticks. Note, however, that the tick arguments are still passed to the scale's tickFormat function if tick format is not also set. Thus, it is valid to set both axis.ticks and axis.tickValues.

# axis.tickSubdivide([count])

Get or set the tick subdivision count. If count is specified, sets the number of uniform subdivision ticks to make between major tick marks and returns the axis. If count is not specified, returns the current subdivision tick count which defaults to zero. The specified count specifies the number of minor ticks, which is one less than the number of subdivisions. For example, axis.tickSubdivide(true) produces one minor tick per major tick, thus cutting the space between each major tick in two. As another example, decimal subdivision is specified as axis.tickSubdivide(9).

# axis.tickSize([major[​[, minor], end]])

Get or set the size of major, minor and end ticks. The end ticks are determined by the associated scale's domain extent, and are part of the generated path domain rather than a tick line. Note that the end ticks may be close or even overlapping with the first or last tick. An end tick size of 0 suppresses end ticks. For example:

axis.tickSize(6); // sets the major, minor and end to 6 
axis.tickSize(6, 0); // sets major and minor to 6, end to 0
axis.tickSize(6, 3, 0); // sets major to 6, minor to 3, and end to 0

# axis.tickPadding([padding])

Set or get the padding between ticks and tick labels. If padding is specified, sets the padding to the specified value in pixels and returns the axis. If padding is not specified, returns the current padding which defaults to 3 pixels.

# axis.tickFormat([format])

Set or get the tick value formatter for labels. If format is specified, sets the format to the specified function and returns the axis. If format is not specified, returns the current format function, which defaults to null. A null format indicates that the scale's default formatter should be used, which is generated by calling scale.tickFormat. In this case, the arguments specified by ticks are likewise passed to scale.tickFormat.

See d3.format for help creating formatters. For example, axis.tickFormat(d3.format(",.0f")) will display integers with comma-grouping for thousands.

Note: for log scales, the number of ticks cannot be customized; however, the number of tick labels can be customized via ticks. Likewise, the tick formatter for log scales is typically specified via ticks rather than tickFormat, so as to preserve the default label-hiding behavior.