Repository files navigation

The axis component renders human-readable reference marks forscales. This alleviates one of the more tedious tasks in visualizing data.

If you use NPM,npm install d3-axis. Otherwise, download thelatest release. You can also load directly fromd3js.org, either as astandalone library or as part ofD3 4.0. (To be useful, you’ll also want to used3-scale andd3-selection, but these are soft dependencies.) AMD, CommonJS, and vanilla environments are supported. In vanilla, ad3 global is exported:

<scriptsrc="https://d3js.org/d3-axis.v1.min.js"></script><script>varaxis=d3.axisLeft(scale);</script>

Try d3-axis in your browser.

Regardless of orientation, axes are always rendered at the origin. To change the position of the axis with respect to the chart, specify atransform attribute on the containing element. For example:

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

The elements created by the axis are considered part of its public API. You can apply external stylesheets or modify the generated axis elements tocustomize the axis appearance.

An axis consists of apath element of class “domain” representing the extent of the scale’s domain, followed by transformedg elements of class “tick” representing each of the scale’s ticks. Each tick has aline element to draw the tick line, and atext element for the tick label. For example, here is a typical bottom-oriented axis:

<gfill="none"font-size="10"font-family="sans-serif"text-anchor="middle"><pathclass="domain"stroke="#000"d="M0.5,6V0.5H880.5V6"></path><gclass="tick"opacity="1"transform="translate(0.5,0)"><linestroke="#000"y2="6"></line><textfill="#000"y="9"dy="0.71em">0.0</text></g><gclass="tick"opacity="1"transform="translate(176.5,0)"><linestroke="#000"y2="6"></line><textfill="#000"y="9"dy="0.71em">0.2</text></g><gclass="tick"opacity="1"transform="translate(352.5,0)"><linestroke="#000"y2="6"></line><textfill="#000"y="9"dy="0.71em">0.4</text></g><gclass="tick"opacity="1"transform="translate(528.5,0)"><linestroke="#000"y2="6"></line><textfill="#000"y="9"dy="0.71em">0.6</text></g><gclass="tick"opacity="1"transform="translate(704.5,0)"><linestroke="#000"y2="6"></line><textfill="#000"y="9"dy="0.71em">0.8</text></g><gclass="tick"opacity="1"transform="translate(880.5,0)"><linestroke="#000"y2="6"></line><textfill="#000"y="9"dy="0.71em">1.0</text></g></g>

The orientation of an axis is fixed; to change the orientation, remove the old axis and create a new axis.

# d3.axisTop(scale)<>

Constructs a new top-oriented axis generator for the givenscale, with emptytick arguments, atick size of 6 andpadding of 3. In this orientation, ticks are drawn above the horizontal domain path.

# d3.axisRight(scale)<>

Constructs a new right-oriented axis generator for the givenscale, with emptytick arguments, atick size of 6 andpadding of 3. In this orientation, ticks are drawn to the right of the vertical domain path.

# d3.axisBottom(scale)<>

Constructs a new bottom-oriented axis generator for the givenscale, with emptytick arguments, atick size of 6 andpadding of 3. In this orientation, ticks are drawn below the horizontal domain path.

# d3.axisLeft(scale)<>

Constructs a new left-oriented axis generator for the givenscale, with emptytick arguments, atick size of 6 andpadding of 3. In this orientation, ticks are drawn to the left of the vertical domain path.

#axis(context)<>

Render the axis to the givencontext, which may be either aselection of SVG containers (either SVG or G elements) or a correspondingtransition.

#axis.scale([scale])<>

Ifscale is specified, sets thescale and returns the axis. Ifscale is not specified, returns the current scale.

#axis.ticks(arguments…)<>
#axis.ticks([count[,specifier]])
#axis.ticks([interval[,specifier]])

Sets thearguments that will be passed toscale.ticks andscale.tickFormat when the axis isrendered, and returns the axis generator. The meaning of thearguments depends on theaxis’ scale type: most commonly, the arguments are a suggestedcount for the number of ticks (or atimeinterval for time scales), and an optionalformatspecifier to customize how the tick values are formatted.

This method has no effect if the scale does not implementscale.ticks, as withband andpoint scales. To set the tick values explicitly, useaxis.tickValues. To set the tick format explicitly, useaxis.tickFormat.

For example, to generate twenty ticks with SI-prefix formatting on a linear scale, say:

axis.ticks(20,"s");

To generate ticks every fifteen minutes with a time scale, say:

axis.ticks(d3.timeMinute.every(15));

This method is also a convenience function foraxis.tickArguments. For example, this:

axis.ticks(10);

Is equivalent to:

axis.tickArguments([10]);

#axis.tickArguments([arguments])<>

Ifarguments is specified, sets thearguments that will be passed toscale.ticks andscale.tickFormat when the axis isrendered, and returns the axis generator. The meaning of thearguments depends on theaxis’ scale type: most commonly, the arguments are a suggestedcount for the number of ticks (or atimeinterval for time scales), and an optionalformatspecifier to customize how the tick values are formatted.

Ifarguments is specified, this method has no effect if the scale does not implementscale.ticks, as withband andpoint scales. To set the tick values explicitly, useaxis.tickValues. To set the tick format explicitly, useaxis.tickFormat.

Ifarguments is not specified, returns the current tick arguments, which defaults to the empty array.

For example, to generate twenty ticks with SI-prefix formatting on a linear scale, say:

axis.tickArguments([20,"s"]);

To generate ticks every fifteen minutes with a time scale, say:

axis.tickArguments([d3.timeMinute.every(15)]);

See alsoaxis.ticks.

#axis.tickValues([values])<>

If avalues array is specified, the specified values are used for ticks rather than using the scale’s automatic tick generator. Ifvalues is null, clears any previously-set explicit tick values and reverts back to the scale’s tick generator. Ifvalues is not specified, returns the current tick values, which defaults to null. For example, to generate ticks at specific values:

varxAxis=d3.axisBottom(x).tickValues([1,2,3,5,8,13,21]);

The explicit tick values take precedent over the tick arguments set byaxis.tickArguments. However, any tick arguments will still be passed to the scale’stickFormat function if a tick format is not also set.

#axis.tickFormat([format])<>

Ifformat is specified, sets the tick format function and returns the axis. Ifformat 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 callingscale.tickFormat. In this case, the arguments specified byaxis.tickArguments are likewise passed toscale.tickFormat.

Seed3-format andd3-time-format for help creating formatters. For example, to display integers with comma-grouping for thousands:

axis.tickFormat(d3.format(",.0f"));

More commonly, a format specifier is passed toaxis.ticks:

axis.ticks(10,",f");

This has the advantage of setting the format precision automatically based on the tick interval.

#axis.tickSize([size])<>

Ifsize is specified, sets theinner andouter tick size to the specified value and returns the axis. Ifsize is not specified, returns the current inner tick size, which defaults to 6.

#axis.tickSizeInner([size])<>

Ifsize is specified, sets the inner tick size to the specified value and returns the axis. Ifsize 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.tickSizeOuter([size])<>

Ifsize is specified, sets the outer tick size to the specified value and returns the axis. Ifsize 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])<>

Ifpadding is specified, sets the padding to the specified value in pixels and returns the axis. Ifpadding is not specified, returns the current padding which defaults to 3 pixels.