d3-axis

What is d3-axis?

The d3-axis package is part of the D3 (Data-Driven Documents) library, which provides a way to easily create and manipulate axes in SVG for data visualization. It supports various types of axes, including horizontal and vertical axes, and allows for customization of tick marks, labels, and other axis properties.

What are d3-axis's main functionalities?

Creating a Bottom Axis

This feature allows you to create a horizontal axis to be placed at the bottom of a chart. The 'scale' argument is a scale function that maps domain values to the range of the axis.

d3.axisBottom(scale)

Creating a Left Axis

This feature enables the creation of a vertical axis to be placed on the left side of a chart. Similar to axisBottom, it requires a scale function that defines the mapping from data values to the graphical representation.

d3.axisLeft(scale)

Customizing Tick Values

With this feature, you can specify the exact values where ticks should be placed on the axis. This is useful for highlighting specific data points or for customizing the distribution of ticks.

axis.tickValues([values])

Other packages similar to d3-axis

chart.js

Chart.js is a powerful, flexible JavaScript charting library. While it provides functionalities for creating various types of charts, including the axes, it differs from d3-axis in that it is a more comprehensive charting solution rather than a specialized tool for axis manipulation.

plotly.js

Plotly.js is another comprehensive charting library that supports a wide range of chart types and interactive features. Similar to Chart.js, it includes capabilities for axis creation and customization but is part of a broader toolkit for data visualization.

README

d3-axis

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

Installing

If you use NPM, npm install d3-axis. Otherwise, download the latest release. You can also load directly from d3js.org, either as a standalone library or as part of D3 4.0. (To be useful, you’ll also want to use d3-scale and d3-selection, but these are soft dependencies.) AMD, CommonJS, and vanilla environments are supported. In vanilla, a d3 global is exported:

<script src="https://d3js.org/d3-axis.v1.min.js"></script>
<script>

var axis = d3.axisLeft(scale);

</script>

Try d3-axis in your browser.

API Reference

Regardless of orientation, axes are always rendered at the origin. To change the position of the axis with respect to the chart, specify a transform attribute on the containing 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);

Once created, the orientation of an axis is fixed. To change the orientation, remove the old axis and create a new 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 to customize the axis appearance. An axis consists of a path element of class “domain” representing the extent of the scale’s domain, followed by transformed g elements of class “tick” representing each of the scale’s ticks. Each tick has a line element to draw the tick line, and a text element for the tick label. For example, here is a typical bottom-oriented axis:

<g fill="none" font-size="10" font-family="sans-serif" text-anchor="middle">
  <path class="domain" stroke="#000" d="M0.5,6V0.5H880.5V6"></path>
  <g class="tick" opacity="1" transform="translate(0,0)">
    <line stroke="#000" y2="6" x1="0.5" x2="0.5"></line>
    <text fill="#000" y="9" x="0.5" dy="0.71em">0.0</text>
  </g>
  <g class="tick" opacity="1" transform="translate(176,0)">
    <line stroke="#000" y2="6" x1="0.5" x2="0.5"></line>
    <text fill="#000" y="9" x="0.5" dy="0.71em">0.2</text>
  </g>
  <g class="tick" opacity="1" transform="translate(352,0)">
    <line stroke="#000" y2="6" x1="0.5" x2="0.5"></line>
    <text fill="#000" y="9" x="0.5" dy="0.71em">0.4</text>
  </g>
  <g class="tick" opacity="1" transform="translate(528,0)">
    <line stroke="#000" y2="6" x1="0.5" x2="0.5"></line>
    <text fill="#000" y="9" x="0.5" dy="0.71em">0.6</text>
  </g>
  <g class="tick" opacity="1" transform="translate(704,0)">
    <line stroke="#000" y2="6" x1="0.5" x2="0.5"></line>
    <text fill="#000" y="9" x="0.5" dy="0.71em">0.8</text>
  </g>
  <g class="tick" opacity="1" transform="translate(880,0)">
    <line stroke="#000" y2="6" x1="0.5" x2="0.5"></line>
    <text fill="#000" y="9" x="0.5" dy="0.71em">1.0</text>
  </g>
</g>

# d3.axisTop(scale)

Constructs a new top-oriented axis generator for the given scale, with empty tick arguments, a tick size of 6 and padding 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 given scale, with empty tick arguments, a tick size of 6 and padding 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 given scale, with empty tick arguments, a tick size of 6 and padding 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 given scale, with empty tick arguments, a tick size of 6 and padding of 3. In this orientation, ticks are drawn to the left of the vertical domain path.

# axis(context)

Render the axis to the given context, which may be either a selection of SVG containers (either SVG or G elements) or a corresponding transition.

# axis.scale([scale])

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

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

Sets the arguments that will be passed to scale.ticks and scale.tickFormat when the axis is rendered, and returns the axis generator. The meaning of the arguments depends on the axis’ scale type: most commonly, the arguments are a suggested count for the number of ticks (or a time interval for time scales), and an optional format specifier to customize how the tick values are formatted.

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 an alternative to setting the tick values explicitly via axis.tickValues, and setting the tick format explicitly via axis.tickFormat. This method is also a convenience function for axis.tickArguments. For example, this:

axis.ticks(10);

Is equivalent to:

axis.tickArguments([10]);

# axis.tickArguments([arguments])

If arguments are specified, sets the arguments that will be passed to scale.ticks and scale.tickFormat when the axis is rendered, and returns the axis generator. The meaning of the arguments depends on the axis’ scale type: most commonly, the arguments are a suggested count for the number of ticks (or a time interval for time scales), and an optional format specifier to customize how the tick values are formatted. This method is a convenient alternative to setting the tick values explicitly via axis.tickValues, and setting the tick format explicitly via axis.tickFormat. If arguments 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)]);

This method is an alternative to setting the tick values explicitly via axis.tickValues, and setting the tick format explicitly via axis.tickFormat. See also axis.ticks.

# 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 and reverts back to the scale’s tick generator. If values is not specified, returns the current tick values, which defaults to null. For example, to generate ticks at specific values:

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

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

# axis.tickFormat([format])

If format is specified, sets the tick format 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 axis.tickArguments are likewise passed to scale.tickFormat.

See d3-format and d3-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 to axis.ticks:

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

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

# axis.tickSize([size])

If size is specified, sets the inner and outer 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.

# axis.tickSizeInner([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.tickSizeOuter([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.