The horizontal (X) and vertical (Y) lines in cartesian charts are referred to as chart axes, and they serve to illustrate the relationships between data points on the graph. This section discusses the different axis types.
Category Copy Link
A category axis is used to display distinct categories or groups of data in a chart.
The category axis shows discrete categories or groups of data, unlike the Number or Time axes which use a continuous scale. For instance, in a bar chart of sales per product, the category axis shows the products as different groups, and the number axis displays the corresponding sale value for each group.
If no axes are supplied, a category axis will be used as the x-axis by default. However, it can also be explicitly configured as shown below:
axes: [
{
type: 'category',
position: 'bottom',
},
],
The category axis will attempt to render an Axis Label, Grid Line and Tick for each category with even spacing.
For a full list of configuration options see Category Axis Options.
Grouped Category Copy Link
A grouped category axis is similar to the regular category axis, with the additional ability to display nested categories or hierarchical groups of data.
To use a grouped category axis, the xKey needs to reference an array of strings, with each string representing a level in the hierarchy.
For example, to create the above example comparing Olympic medal counts by hierarchical location, the data must include an array with the regions, countries, and cities.
data: [
{ location: ['Europe', 'United Kingdom', 'London'], gold: 27, silver: 23, bronze: 17 },
{ location: ['Europe', 'United Kingdom', 'Manchester'], gold: 12, silver: 8, bronze: 10 },
{ location: ['Asia', 'China', 'Beijing'], gold: 38, silver: 32, bronze: 18 },
{ location: ['Asia', 'China', 'Shanghai'], gold: 20, silver: 15, bronze: 12 },
{ location: ['Asia', 'Japan', 'Tokyo'], gold: 27, silver: 14, bronze: 17 },
{ location: ['North America', 'United States', 'Los Angeles'], gold: 46, silver: 37, bronze: 38 },
{ location: ['North America', 'Canada', 'Toronto'], gold: 8, silver: 6, bronze: 10 },
],
The grouped category axis will render Axis Labels, Grid Lines, and Ticks for each level in the hierarchy, aligning them to visually represent the nested relationships between categories.
Ticks and labels for all levels inherit styles from the axis options by default. To style each level differently, use the depthOptions array, where each entry corresponds to a hierarchy level, starting at the leaf level.
type: 'grouped-category',
depthOptions: [
{}, // Skip depth 0 - the nearest to the axis, no unique styles.
{ label: { fontWeight: 'bold' } }, // depth 1
{ label: { fontSize: 10 } }, //depth 2
],
Number Copy Link
A number axis is used to display continuous numerical values in a chart.
The number axis displays continuous numerical values, unlike the Category axis which displays discrete categories or groups of data. This means that while categories are spaced out evenly, the distance between values in a number axis will depend on their magnitude.
Instead of using an Axis Interval with one item per value, the number axis will determine the range of all values, round it up and try to segment the rounded range with evenly spaced intervals.
If no axes are supplied, a number axis will be used as the y-axis by default. However, it can also be explicitly configured as shown below:
axes: [
{
type: 'number',
position: 'left',
},
],
For a full list of configuration options see Number Axis Options.
Log Copy Link
If the range of values is very wide, the log axis can be used instead of the number axis. For example, because the number axis uses a linear scale, same changes in magnitude result in the same pixel distance.
The log axis uses a log scale, where same percentage changes in magnitude result in the same pixel distance. In other words, the pixel distance between 10 and 100, and 100 and 1000 will be the same because both ranges represent the same percentage increase. Whereas, if the number axis was used, the second distance would be 10 times larger than the first.
The above property of the log axis can also be useful in financial charts. For example, if your rate of return on an investment stays consistent over time, the investment value chart will look like a straight line.
By default, if the data domain has 5 or more orders of magnitude, the log axis attempts to render 5 ticks. Otherwise, 10 ticks (the logarithm base) is rendered per order of magnitude. For example a data domain of [1, 100] with 2 orders of magnitude, will show 1, 2, 3, 4,5, 6, 7, 8, 9, 10, 20, 30, 40, 50, 60, 70, 80, 90, 100.
Depending on the data domain and chart size, using a larger value for the tick: { minSpacing: xxx } config might be necessary to reduce the number of ticks.
{
type: 'log',
position: 'left',
minSpacing: 200,
}
The log axis uses the common logarithm (base 10) by default. The base config allows you to change the base to any number you like, for example Math.E for natural or 2 for binary logarithms:
{
type: 'log',
position: 'left',
base: 2,
}
For a full list of configuration options see Log Axis Options.
These configurations above are demonstrated in the following example:
The domain of a log axis should be strictly positive or strictly negative (because there's no power you can raise a number to that will yield zero). For that reason, any non-conforming domain will be clipped to conformity. For example, [0, 10] will be clipped to [1, 10]. If the data domain crosses 0, for example [-10, 5], no data will be rendered. It is often desirable to set the min or max property of the axis manually. In this case it can be max: -1.
Time Copy Link
There are three methods of displaying time along an axis.
- Time Axis - Data is shown on a continuous scale.
- Time Axis + unit - Each 'unit' has a dedicated band within the domain.
- Ordinal Time - Only provided values are shown, with missing values omitted.
The time axis is similar to the number axis in the sense that it is also used to plot continuous values. The time axis can even be used with numeric data (in addition to Date objects), but the numbers will be interpreted as JavaScript timestamps. The time axis differs from the number axis in tick segmentation and label formatting. For example, you could choose to place a tick every 5 minutes, every month, or every Friday.
The time axis also supports specifier strings to control the way time values are presented as labels. For example, the %H:%M:%S specifier string will instruct the axis to format a time value like new Date('Mon Apr 17 2023 12:43:17') or 1681735397000 as '12:43:17'. Time axes are typically used as x-axes and placed at the bottom of a chart. The simplest time axis config looks like this:
{
type: 'time',
position: 'bottom',
}
For a full list of configuration options see Time Axis Options.
Unit Time Copy Link
The Time Axis defaults to using a continuous scale. This accurately portrays the difference between each time value, but this is not always desired. For example, data points will not be evenly spaced when plotting monthly data, because of the inconsistent number of days across months.
The unit property on the Time Axis can be used to specify the period of each data point. It will plot the data with evenly spaced bands for each unit with the domain.
{
type: 'time',
position: 'bottom',
unit: 'month',
}
In this example of unit: 'month', any units smaller than 'month' will be ignored. This means that values for 01 Jan and 28 Feb will be displayed identically to values of 31 Jan and 01 Feb.
Valid unit values are 'millisecond', 'second', 'minute', 'hour', 'day', 'month', 'year', or a TimeInterval object.
The Unit Time Axis does not aggregate data, so you should ensure that each series only has one value per unit.
For a full list of configuration options see Time Axis Options.
Ordinal Time Copy Link
The Ordinal Time Axis is used to plot time-bound data on a band scale. Unlike a linear Time Axis, which represents time with consistent intervals, the ordinal time scale maintains the order of time values but does not represent the exact time span between them.
Data points plotted along an Ordinal Time Axis will be arranged according to their position in time, ignoring the time intervals between them.
For example, if the Ordinal Time Axis is used to plot daily values but there are no data points for the weekend, values for Friday and Monday will be equally spaced, without gaps for Saturday and Sunday.
The Ordinal Time Axis can be used with Date objects and numeric data, the numbers will be interpreted as JavaScript timestamps.
This axis follows the tick segmentation and label formatting of the Time Axis.
Ordinal Time axes are commonly used for financial data on the x-axis, usually placed at the bottom of a chart. A basic Ordinal Time Axis configuration looks like this:
{
type: 'ordinal-time',
position: 'bottom',
}
For a full list of configuration options see Ordinal Time Axis Options.
The difference between a continuous Time Axis, a Unit Time Axis, and an Ordinal Time Axis is demonstrated in the following example:
API Reference Copy Link
Next Up Copy Link
Continue to the next section to learn about the Axis Intervals.