Component for the creation of Axes in chrt. The axes define the area where the values are displayed and they help the reader to make sense of the position of the elements in the chart. Axes are based on scales (quantitative and categorical).
The component provides two types of axes: the X Axis (xAxis
) which runs horizontally and the Y Axis (yAxis
), which runs vertically.
A chrtAxis is formed by a set of visual elements:
- One axis line
- Ticks
- Labels
- Axis range
- Axis title
One chart can have multiple Axes, and they can be oriented (left/right and top/bottom).
For use with Webpack, Rollup, or other Node-based bundlers, chrt-axis
can be installed as a standalone module via a package manager such as Yarn or npm.
npm install chrt-axis chrt-core
chrt-axis
can be used as part of the chrt
package:
npm install chrt
chrt-axis
is distributed as an ES module; see Sindre Sorhus’s guide for more information.
import Chrt from 'chrt-core';
import { xAxis, yAxis } from 'chrt-axis';
Chrt()
.data([1,2,3,4,5,6])
.add(
xAxis()
)
.add(
yAxis()
)
In vanilla HTML, chrt-axis
can be imported as an ES module, (i.e. from Skypack):
<div id="chart"></div>
<script type="module">
import Chrt from 'https://cdn.skypack.dev/chrt-core';
import {xAxis, yAxis} from 'https://cdn.skypack.dev/chrt-axis';
const chart = Chrt()
.data([1,2,3,4,5,6])
.add(xAxis())
.add(yAxis())
document
.querySelector('#chart')
.appendChild(chart.node())
</script>
For legacy environments, you can load the chrt
UMD bundle from an npm-based CDN such as jsdelivr:
<div id="chart"></div>
<script src="https://cdn.jsdelivr.net/npm/chrt@latest/dist/chrt.min.js"></script>
<script>
chrt.Chrt()
.node(document.getElementById('chart'))
.data([0,1,2,3,4,5])
.add(
chrt.xAxis()
)
.add(
chrt.yAxis()
)
</script>
X Axis (xAxis
) runs horizontally and it can be oriented at the bottom or top of the chart.
When xAxis
is added without arguments, chrt
builds a default axis with a computed number of ticks based on the x scale. Example usage:
Chrt()
.add(
xAxis()
)
When xAxis
is added with count
, chrt
builds a default axis with a suggested number of ticks based on the x scale. Example usage:
Chrt()
.add(
xAxis(5)
)
When xAxis
is added with a scaleName
, chrt
builds an axis by computing the ticks based on the custom scale called scaleName
. Example usage:
Chrt()
.add(
xAxis(10, 'customScaleName')
)
If widthValue
is specified, it sets the thickness of the Axis line accordingly. If widthValue
is null
, this function will return the thickness of the line of the Axis. If widthValue
is a Number
or a function
, width
will set the thickness of the line of the Axis. Example usage:
Chrt()
.add(
xAxis()
.width(2)
)
If colorValue
is specified, it sets the color of the Axis line accordingly. If colorValue
is null
, this function will return the color of the line of the Axis. If colorValue
is a String
or a function
, color
will set the color of the line of the Axis. Example usage:
Chrt()
.add(
xAxis()
.color('#f00')
)
If show
is specified, it sets visibility the Axis accordingly. If show
is null
, this function will return the current visibility of the Axis. If show
is a Boolean
or a function
, showAxis
will define whether the Axis is visible or not. Example usage:
Chrt()
.add(
xAxis()
.showAxis(false)
)
Shortcut for showAxis(false)
, when called on the Axis it will hide the axis. Example usage:
Chrt()
.add(
xAxis()
.hideAxis()
)
Sets the orientation of the X axis. If no argument is passed, the current orientation is returned.
// Set the orientation of the X axis to "top"
xAxis.orient("top");
// Get the current orientation of the X axis
const currentOrientation = xAxis.orient();
console.log(currentOrientation); // Output: "top"
Note: The yAxis
object also has an orient()
method with similar usage.
Sets the formatting function for the labels in the x-axis. The function takes one argument, the value of the tick, and returns the formatted string for that value.
xAxis.format(new Intl.NumberFormat('de-DE', { style: 'currency', currency: 'EUR' }).format);
Sets the vertical position of the x-axis line relative to the origin of the chart. By default, the x-axis line is positioned at the value 0 on the y-axis.
value
is the value representing the y-coordinate of the x-axis line. If not provided, the line will be positioned at the y-coordinate of the minimum value of the y-axis scale.
Usage Example:
Suppose you have a chart that displays the number of sales of a product over time. The y-axis represents the number of sales, and the x-axis represents the time. The x-axis line is currently positioned at 0 on the y-axis, which is the default value. You want to position the x-axis line at the value 100 on the y-axis instead. You can do this using the xAxis.zero()
function as follows:
// set the vertical position of the x-axis line to 100 on the y-axis
xAxis.zero(100);
If count
is specified, it suggests the count for the number of ticks the Axis accordingly. If count
is null
, this function will return the list of the ticks the Axis. If count
is a Number
or a function
, ticks
will define a suggested count for the number of ticks in the Axis that will be calculated by the axis scale.
Chrt()
.add(
xAxis()
.ticks(10)
)
Sure! Here are the API specs for ticksColor
and ticksWidth
:
Sets the color of the ticks to the specified color
value, or returns the current tick color if color
is not provided.
// Set the color of ticks using a function
xAxis.ticksColor((d, i) => {
if (i % 2 === 0) {
return 'red';
} else {
return 'blue';
}
});
// Get the current color of ticks
const currentColor = xAxis.ticksColor();
Sets the thickness of the ticks to the specified width
value, or returns the current tick width if width
is not provided.
// Set the width of ticks using a function
xAxis.ticksWidth((d, i) => {
if (i % 2 === 0) {
return 2;
} else {
return 1;
}
});
// Get the current width of ticks
const currentWidth = xAxis.ticksWidth();
If tickLength
is specified, it sets the length of the ticks of the Axis accordingly. If tickLength
is null
, this function will return the length of the ticks of the Axis. If tickLength
is a Number
or a function
, setTickLength
will set the length of the ticks of the Axis. Example usage:
Chrt()
.add(
xAxis()
.setTickLength(5)
)
If tickPosition
is specified, it sets the position of the ticks of the Axis accordingly. If tickPosition
is null
, this function will return the current position of the ticks of the Axis. If tickPosition
is a String
or a function
, setTickPosition
will set the length of the ticks of the Axis. The accepted values of tickPosition
are inside
and outside
(default position). Example usage:
Chrt()
.add(
xAxis()
.setTickPosition('inside')
.setTickPosition('outside')
)
Shows or hides the ticks on the axis based on the parameter passed. The parameter can be a function, a boolean value, a number, or an array of values. When a function is passed, it is used to filter the ticks based on their data and index. When a boolean value is passed, all ticks are either shown or hidden. When a number is passed, only the tick with the corresponding value is shown. When an array of values is passed, only the ticks with values in the array are shown.
Example usage:
Show every other tick:
axis.showTicks((d, i) => i % 2 === 0);
Show all ticks:
axis.showTicks(true);
Hide all ticks:
axis.showTicks(false);
Show only the tick with value 10:
xAxis().showTicks(10);
Show only ticks with values 10, 20, and 30:
xAxis().showTicks([10, 20, 30]);
Hides the ticks on the axis based on the parameter passed. It is essentially the opposite of the showTicks()
function. The parameter can be a function, a boolean value, a number, or an array of values. When a function is passed, it is used to filter the ticks based on their data and index. When a boolean value is passed, all ticks are either shown or hidden. When a number is passed, only the tick with the corresponding value is shown. When an array of values is passed, only the ticks with values in the array are shown.
Example usage:
Hide every other tick:
xAxis.hideTicks((d, i) => i % 2 === 0);
Hide all ticks:
xAxis.hideTicks(true);
Show all ticks:
xAxis.hideTicks(false);
Hide only the tick with value 10:
xAxis.hideTicks(10);
Hide ticks with values 10, 20, and 30:
xAxis.hideTicks([10, 20, 30]);
Shows or hides the first tick on the axis. If show
is true
, only the first tick is shown and all other ticks are hidden. If show
is false
, only the first tick is hidden and all other ticks are shown.
Example usage:
Show the first tick:
xAxis.firstTick();
Hide the first tick:
xAxis.firstTick(false);
Note that if you want to customize the appearance of the first tick (e.g., make it a different color or size), you can use the ticksColor()
, ticksLength()
and ticksWidth()
functions to apply a different style to the first tick.
Shows or hides the last tick on the axis. If show
is true
, only the last tick is shown and all other ticks are hidden. If show
is false
, only the last tick is hidden and all other ticks are shown.
Example usage:
Show the last tick:
xAxis.lastTick();
Hide the last tick:
xAxis.lastTick(false);
Shows or hides both the first and the last ticks on the axis. If show
is true
, only the first and last ticks are shown and all other ticks are hidden. If show
is false
, only the first and last ticks are hidden and all other ticks are shown.
Example usage:
Show the first and last ticks:
xAxis.firstAndLastTicks();
Hide the first and last ticks:
xAxis.firstAndLastTicks(false);
Sets the offset of the labels along the direction of the x-axis. A positive offset moves the labels to the right, while a negative offset moves the labels to the left. A value of 0 means no offset, and the label will be aligned with its position. If a function is provided as the offset parameter, it will be called for each label with the value
and index
of the label as parameters.
Example usage:
Y Axis (yAxis
) runs vertically and it can be oriented at the left or right of the chart.