SVG Axes

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 D3’s quantitative, time and ordinal 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])

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])

If orientation is specified, sets the orientation and returns the axis. If orientation is not specified, returns the current orientation which defaults to "bottom". The following orientations are supported:

• "top" - horizontal axis with ticks above the domain path
• "bottom" - horizontal axis with ticks below the domain path
• "left" - vertical axis with ticks to the left of the domain path
• "right" - vertical axis with ticks to the right of the domain path

If the specified orientation is not one of the supported values, the axis reverts to the default orientation. Changing the orientation affects the position of the ticks and their labels in relation to the axis path, but does not change the position of the axis itself; to change the position of the axis with respect to the plot, specify a transform attribute on the containing g element.

axis.ticks([arguments…])

If arguments are specified, stores the specified arguments for subsequent use in generating ticks and returns the axis. The arguments will later be passed to scale.ticks to generate tick values (unless tick values are specified explicitly via axis.tickValues). The arguments are also passed to the scale’s tickFormat method to generate the default tick format. If no arguments are specified, returns the current tick arguments, which default to [10].

Suitable arguments depends on the associated scale: for a linear scale, you might specify a tick count such as axis.ticks(20); for a log scale, you might specify both a count and a tick format; for a time scale, a time interval such as axis.ticks(d3.time.minutes, 15) might be appropriate.

axis.tickValues([values])

If a values array is specified, the specified values are used for ticks, rather than using the scale's automatic 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, which defaults to null. 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. However, any tick arguments will still be passed to the scale's tickFormat function if a tick format is not also set; thus, it may be valid to set both axis.ticks and axis.tickValues.

axis.tickSize([inner, outer])

If inner, outer are specified, sets the inner and outer tick sizes to the specified value and returns the axis. If inner, outer are not specified, returns the current inner tick size, which defaults to 6.

axis.innerTickSize([size])

If size is specified, sets the inner tick size to the specified value and returns the axis. If size is not specified, returns the current inner tick size, which defaults to 6. The inner tick size controls the length of the tick lines, offset from the native position of the axis.

axis.outerTickSize([size])

If size is specified, sets the outer tick size to the specified value and returns the axis. If size is not specified, returns the current outer tick size, which defaults to 6. The outer tick size controls the length of the square ends of the domain path, offset from the native position of the axis. Thus, the “outer ticks” are not actually ticks but part of the domain path, and their position is determined by the associated scale's domain extent. Thus, outer ticks may overlap with the first or last inner tick. An outer tick size of 0 suppresses the square ends of the domain path, instead producing a straight line.

axis.tickPadding([padding])

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])

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. Defining the formatter first: var commasFormatter = d3.format(",.0f") lets you to call it as a function of your data, for example, to add currency units in front of the comma-grouped integers: .tickFormat(function(d) { return "$" + commasFormatter(d); }).

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.