JavaScript Charts: Axes

This section explains what chart axes are, how to configure and style them, and which axis type to use in which situation.

A chart uses axes to plot data such as categories and values by converting them to screen coordinates. Since any point on the screen is an (x, y) pair of coordinates, a chart needs two orthogonal axes to plot the data — a horizontal axis to determine the x position of a point and a vertical axis to determine the y position. Axes also show ticks, labels and grid lines to help the user navigate a chart.

The charting library supports four axis types:

Category
Number
Log
Time

Each type is tailored to be used with certain types of data. An axis can be positioned to any side of a chart — 'top', 'right', 'bottom', or 'left'. Just like with series, the axes can be specified by setting the corresponding axes array property of a chart.

Axes are only supported in cartesian charts, not polar. For example, you can't use axes with pie series.

Category Axis

The category axis is meant to be used with relatively small datasets of discrete values or categories, such as sales per product, person or quarter, where product, person and quarter are categories.

The category axis attempts to render a tick, a label and a grid line for each category, and spaces out all ticks evenly.

The category axis is used as the x-axis by default, positioned at the bottom of a chart.

The simplest category axis config looks like this:

{
    type: 'category',
    position: 'bottom'
}

Number Axis

The number axis is meant to be used as a value axis. While categories are spaced out evenly, the distance between values depends on their magnitude.

Instead of using one tick 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 ticks.

The number axis is used as the y-axis by default, positioned to the left a chart.

Here's the simplest number axis config:

{
    type: 'number',
    position: 'left'
}

Log Axis

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',
    tick: {
      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
}

All of the above points are demonstrated by the example below.

Example: Number Axis vs Log Axis

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 Axis

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 Unix 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('Tue Feb 04 202 15:08:03') or 1580828883000 as '15:08:03'. 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'
}

Axis Title

Sometimes it may not be obvious what a chart's dimension represents. For example, you might see numbers on a chart's axis and not be able to tell if they're millimetres, percentages, dollars, or something else! It can also be helpful to provide extra information. For example, category axis labels can clearly show people's names, but it might be worth knowing that they are a company's best performing sales people.

Luckily, an axis can have a title just like a chart. In the example below we can use axis titles to point out that:

the horizontal dimension shows desktop operating systems
the vertical dimension shows their percentage market share

Please see the API reference for axis title styling options like font and colour.

Example: Axis Title

Axis Ticks

Axis ticks are displayed at intervals along each axis, and are also used to determine the position and frequency of the axis labels and grid lines.

Tick Placement

Category axes show a tick for every category. Number and time axes will display around 5 ticks depending on the available space.

It is possible to customise or override this default behaviour by using one of the following options.

Min and Max Spacing - used to control the pixel gap between ticks
Interval - used to place a tick at regular intervals
Values - used to place a tick at specified values

Tick Min and Max Spacing

tick.minSpacing and tick.maxSpaxing modify the default behaviour by specifying the approximate minimum and maximum pixel gap which should be present between ticks. One or both options can be provided. An appropriate number of ticks will be generated to satisfy the provided tick.minSpacing and tick.maxSpacing constraints. This number will vary depending on the rendered size of the chart.

tick: {
    minSpacing: 50,
    maxSpacing: 200,
}

Tick Interval

tick.interval is the exact step value between ticks, specified in the units of the axis.

For number axes, the interval property should be a number. A tick will be shown every interval value in the axis range. For example, an interval of 30 will show 0, 30, 60, 90 etc.

tick: {
    interval: 30,
}

For log axes, the interval property should be a number. This is used to step the exponent that the logarithm base is raised to. For example an interval of 2 will show 10^0, 10^2, 10^4 etc.

For time axes the interval property should be a time interval such as time.month, to show a tick every month, or an interval derived from one of the predefined intervals, such as time.month.every(3).

tick: {
    interval: time.month,
}

Other available time intervals are: year, month, day, hour, minute, second, millisecond. There are also some UTC time intervals available: utcYear, utcMonth, utcDay, utcYear, utcMinute.

If the interval property of a time axis is set to a number, this will be interpreted as milliseconds.

If the configured interval results in too many ticks given the data domain and chart size, it will be ignored and the default tick behaviour will be applied.

The example below demonstrates the usage of time intervals:

time.month will produce monthly ticks.
time.month.every(2) will generate ticks for every second month.

{
    type: 'time',
    tick: {
        interval: time.month.every(2)
    }
}

Example: Time Axis Label Format

Tick Values

tick.values can be used to configure the exact array of tick values to display. This should either be an array of number, date or string values depending on the axis type.

These values will also be used as the tick labels unless a label.format or label.formatter is configured.

tick: {
    values: [-50, -25, 0, 25, 50],
}

Example: Axis Tick Placement

The example below demonstrates how the tick.minSpacing, tick.maxSpacing, tick.interval and tick.values properties can be used to control the placement of the ticks.

There are buttons at the top to change between the different options.
There is a grab handle in the bottom right to allow resizing of the chart to see how the ticks change with available space.

Example: Axis Tick Placement

Tick Styling

The width, size and color of chart axis ticks can be configured as explained in the API reference below. These configs apply to all axis types.

Axis Labels

The axis renders a label next to every tick to show the tick's value. Chart axis labels support the same font and colour options as the axis title. Additionally, the distance of the labels from the ticks and their rotation can be configured via the padding, rotation and autoRotate properties respectively.

Label Rotation & Skipping

Label rotation allows a trade-off to be made between space occupied by the axis, series area, and readability of the axis labels.

Three rotation approaches are available:

No rotation. X-axis labels are parallel to the axis, Y-axis labels are perpendicular.
Setting a fixed rotation from the axis via the rotation property.
Enabling automatic rotation via the autoRotate property, and optionally specifying a rotation angle via the autoRotateAngle property. Rotation is applied if any label will be wider than the gap between ticks.

Label skipping is performed automatically when there is a high likelihood of collisions. To disable this, set label.avoidCollisions to false:

{
    label: {
      avoidCollisions: false
    }
}

If autoRotate is enabled, rotation will be attempted first to find a label fit, before label skipping applies. Category axes have autoRotate enabled by default with the default autoRotateAngle of 335.

When label.avoidCollisions is true, the axis labels are dropped if they do not have a minimum of 10px between them. This minimum gap between the axis labels can be configured using the label.minSpacing property:

{
    label: {
      minSpacing: 20
    }
}

The following example demonstrates label rotation and skipping:

There is a grab handle in the bottom right to allow resizing of the chart to see how labels change with available space.
Initially both axes have defaults applied. The X-axis is a category axis so autoRotate is enabled by default.
The first row of buttons at the top change the configuration of both axes to allow all rotation behaviours to be viewed.
The second row of buttons allow switching between X-axis types and labels.

Example: Axis Label Rotation & Skipping

Label Formatting

A label formatter function can be used to change the value displayed in the label. It's a handy feature when you need to show units next to values or format number values to a certain precision.

A label formatter function receives a single params object which contains:

the raw value of the label (without the default formatting applied)
the index of the label in the data array
the number of fractionDigits, if the value is a number
the default label formatter, if the axis is a time axis

For example, to add '%' units next to number values, you can use the following formatter function:

formatter: function(params) {
    return params.value + '%';
}

Example: Axis Label Formatter

Number Label Format String

For number axes, a format string can be provided, which will be used to format the numbers for display as axis labels. The format string may contain the following directives, which reflect those from Python's format specification:

[[fill]align][sign][#][0][width][grouping_option][.precision][type]

Where:

fill - Can be any character.
align:
- > - Forces the field to be right-aligned within the available space (default).
- < - Forces the field to be left-aligned within the available space.
- ^ - Forces the field to be centered within the available space.
- = - Like >, but with any sign and symbol to the left of any padding.
sign:
- - - Nothing for zero or positive and a minus sign for negative (default).
- + - A plus sign for zero or positive and a minus sign for negative.
- ( - Nothing for zero or positive and parentheses for negative.
- - A space for zero or positive and a minus sign for negative.
symbol:
- $ - Apply the $ currency symbol
- # - For binary, octal, or hexadecimal notation, prefix by 0b, 0o, or 0x, respectively.
zero - The 0 option enables zero-padding. Implicitly sets fill to 0 and align to =.
width - The width defines the minimum field width. If not specified, then the width will be determined by the content.
comma - The comma , option enables the use of a group separator, such as a comma for thousands.
precision - Depending on the type, the precision either indicates the number of digits that follow the decimal point (types f and %), or the number of significant digits (types , e, g, r, s and p). If the precision is not specified, it defaults to 6 for all types except (none), which defaults to 12. Precision is ignored for integer formats (types b, o, d, x, X and c).
trim - The ~ option trims insignificant trailing zeros across all format types. This is most commonly used in conjunction with types r, e, s and %.
type - Determines how the data should be presented:
- % - Multiply by 100, and then decimal notation with a percent sign.
- b - Binary notation, rounded to integer.
- c - Converts the integer to the corresponding unicode character before printing.
- d - Decimal notation, rounded to integer.
- e - Exponent notation.
- f - Fixed point notation.
- g - Either decimal or exponent notation, rounded to significant digits.
- o - Octal notation, rounded to integer.
- p - Multiply by 100, round to significant digits, and then decimal notation with a percent sign.
- r - Decimal notation, rounded to significant digits.
- s - Decimal notation with a SI prefix, rounded to significant digits.
- x - Hexadecimal notation, using lower-case letters, rounded to integer.
- X - Hexadecimal notation, using upper-case letters, rounded to integer.

If you want to have a formatted value in the middle of some string, you have to wrap it in #{}, so that it's clear where the number format begins and ends. For example: I'm #{0>2.0f} years old.

The label config of the left axis in the example below uses the '🌧️ #{0>2.1f} °C' specifier string for the format property to format numbers as integers padded to left with zeros to achieve a consistent 2-digit width.

Notice that we wrapped the number format in #{} since we want to prepend the formatted value with the weather icon and to append the units used at the end.

Example: Number Axis Label Format

Number Currency Format

Let's take a look at another example that illustrates a common requirement of formatting numbers as currency. Note that we are using:

the s SI prefix directive to shorten big numbers by using smaller numbers in combination with units, so that 3500000 becomes 3.5M for example
the ~ trim option to trim all insignificant trailing zeros from the formatted value, so that 3.0M becomes 3M for example
the $ option so that the formatted value is prefixed by the $ symbol
the formatter function in addition to the format config to convert certain SI units to currency units

The last point deserves a more in-depth explanation. Because the currency units don't match the SI units exactly, we have to convert certain SI units to their currency counterparts. For example, the SI unit for thousands is k for kilo, M for mega, G for giga and so on. With currencies though it's typical to format thousands as K, while M is the same for million and B (rather than G) is used to denote a billion.

So how do we replace k with K and G with B? To do that, we need to provide a formatter function in addition to our format string. The formatter function receives the unformatted value, as well as the formatter function generated from the format config we provided. So all we have to do is to format the original value using that generated formatter params.formatter(params.value) and replace the SI units with the currency ones .replace('k', 'K').replace('G', 'B').

Example: Number Axis Currency Format

Time Label Format String

For time axes, a format string can be provided, which will be used to format the dates for display as axis labels. The format string may contain the following directives, which reflect those from Python's strftime:

%a - abbreviated weekday name.*
%A - full weekday name.*
%b - abbreviated month name.*
%B - full month name.*
%c - the locale’s date and time, such as %x, %X.*
%d - zero-padded day of the month as a decimal number [01,31].
%e - space-padded day of the month as a decimal number [ 1,31]; equivalent to %_d.
%f - microseconds as a decimal number [000000,999999].
%H - hour (24-hour clock) as a decimal number [00,23].
%I - hour (12-hour clock) as a decimal number [01,12].
%j - day of the year as a decimal number [001,366].
%m - month as a decimal number [01,12].
%M - minute as a decimal number [00,59].
%L - milliseconds as a decimal number [000,999].
%p - either AM or PM.*
%Q - milliseconds since UNIX epoch.
%s - seconds since UNIX epoch.
%S - second as a decimal number [00,61].
%u - Monday-based (ISO) weekday as a decimal number [1,7].
%U - Sunday-based week of the year as a decimal number [00,53].
%V - ISO 8601 week number of the year as a decimal number [01, 53].
%w - Sunday-based weekday as a decimal number [0,6].
%W - Monday-based week of the year as a decimal number [00,53].
%x - the locale’s date, such as %-m/%-d/%Y.*
%X - the locale’s time, such as %-I:%M:%S %p.*
%y - year without century as a decimal number [00,99].
%Y - year with century as a decimal number.
%Z - time zone offset, such as -0700, -07:00, -07, or Z.
%% - a literal percent sign (%).

Directives marked with an asterisk (*) may be affected by the locale definition.

For %U, all days in a new year preceding the first Sunday are considered to be in week 0.
For %W, all days in a new year preceding the first Monday are considered to be in week 0.

For %V, per the strftime man page:

In this system, weeks start on a Monday, and are numbered from 01, for the first week, up to 52 or 53, for the last week. Week 1 is the first week where four or more days fall within the new year (or, synonymously, week 01 is: the first week of the year that contains a Thursday; or, the week that has 4 January in it).

The % sign indicating a directive may be immediately followed by a padding modifier:

0 - zero-padding
_ - space-padding
(nothing) - disable padding

If no padding modifier is specified, the default is 0 for all directives except %e, which defaults to _.

The label config of the bottom axis in the example below uses the '%b %Y' specifier string for the format property to format dates as the abbreviated name of the month followed by the full year.

Notice that the label.format property only affects label formatting but not segmentation. The fact that axis labels were configured to show the name of the month and the year doesn't mean that the axis will show a tick every month. To ensure that it does, we also set the tick.interval config to use the time.month interval.

Please see the Axis Ticks section to learn more about tick intervals.

Axis Grid Lines

Chart axes feature grid lines by default. Grid lines extend from axis ticks on the other side of the axis into the series area, so that it's easy to trace a series item such as a marker to a corresponding tick/label.

Grid lines have the same stroke width as ticks.

Grid lines of each axis can be styled individually via the gridStyle config. The config takes an array of objects with two properties:

stroke: colour string in hex, named, rgb, or rgba format.
lineDash: an array of numbers that specify distances to alternately draw a line and a gap. If the number of elements in the array is odd, the elements of the array get copied and concatenated. For example, [5, 15, 25] will become [5, 15, 25, 5, 15, 25]. If the array is empty, the grid lines will be solid without any dashes.

Each config object in the gridStyle array is alternately applied to the grid lines of the axis.

Example: Grid Lines

Example: Axis Grid Lines

Multiple axes in a single direction

If you have two different datasets (each represented by its own series) but they are on vastly different scales, it is possible to have one series be coordinated by one axis and the other series coordinated by another axis, all in a single chart.

If this is the case, the charting library will need some help in the form of an extra axis config to figure out which series should be coordinated by which axes. By setting the axis' keys config to the keys of the series in question, you let the charting library know that all series that use that those keys will be coordinated by this axis, as illustrated by the example below.

Example: Multiple y-axes

Note, that we are:

using two number axis configurations in the axes array
position one number axis to the left and the other to the right of the chart
set the left number axis keys to match the yKeys of the column series
set the right number axis keys to match the yKey of the line series

Example: Multiple y-axes

Cross Lines

Cross lines display a vertical or horizontal line or region running across a desired chart region. This feature can be useful for data analysis as the cross lines or shaded regions will emphasise trends and draw attention to important information such as a threshold. Cross lines are not supported on polar (pie, doughnut) or treemap charts.

To render a cross line at a specific data value associated with a particular axis, the crossLines property needs to be specified on the individual axes options objects. The cross lines will span the entire chart width or height depending on which axis they are configured on.

axes: [
	{
		position: 'bottom',
		type: 'number',
		crossLines: [
			// an Array of cross lines to be displayed at specific values at the bottom axis.
			{
				type: 'line',
				value: 20
			}
		]
	}
]

The snippet above will render a vertical line running across the height of the chart at the data value 20 on the bottom axis.

To display a region bound by two lines, the cross line type can be configured to range and the range property set to an array containing two data values corresponding to the boundaries of the cross line region:

axes: [
	{
		position: 'right',
		type: 'number',
		crossLines: [
			// an Array of cross lines to be displayed at specific values at the right axis.
			{
				type: 'range',
				range: [10, 20]
			}
		]
	}
]

The snippet above will mark a horizontal region between the values 10 and 20, running across the width of the chart.

Cross lines styles such as stroke, strokeWidth and fill are customisable via AgCrossLineOptions. A label can also be added and positioned with respect to the cross line.

crossLines: [
  {
    type: 'range',
    range: ['apple', 'orange'],
    label: {
      text: 'Price Peak',
      position: 'top',
      fontSize: 14,
      // other cross line label options...
    },
    strokeWidth: 0,
    fill: '#7290C4',
    fillOpacity: 0.4,
  },
],

Please see the API reference for the full cross lines styling options.

Example: Cross Lines

The example below demonstrates how one or more cross lines can be configured in each axis direction. Note that:

Data values can be numbers or categories such as string values or Date objects in accordance with values provided in the chart data.
The left Y axis has cross lines with type line, so the value property on each cross lines options object is used to position the lines on the chart.
The bottom X axis has a cross line of type range; the range property is used to configure the range of the cross line boundaries.

Example: Cross Lines

Axis API Reference

Properties available on the AgBaseCartesianAxisOptions interface.

	`position` AgCartesianAxisPosition	The position on the chart where the axis should be rendered. `position: AgCartesianAxisPosition; type AgCartesianAxisPosition = 'top' \| 'right' \| 'bottom' \| 'left'`
	`title` AgAxisCaptionOptions	Configuration for the title shown next to the axis. title: AgAxisCaptionOptions; interface AgAxisCaptionOptions { // Whether or not the title should be shown. enabled?: boolean; // The text to show in the title. text?: string; // The font style to use for the title. fontStyle?: FontStyle; // The font weight to use for the title. fontWeight?: FontWeight; // The font size in pixels to use for the title. fontSize?: FontSize; // The font family to use for the title. fontFamily?: FontFamily; // The colour to use for the title. color?: CssColor; } type FontStyle = 'normal' \| 'italic' \| 'oblique' type FontWeight = 'normal' \| 'bold' \| 'bolder' \| 'lighter' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900' type FontSize = number type FontFamily = string type CssColor = string
	`line` AgAxisLineOptions	Configuration for the axis line. `line: AgAxisLineOptions; interface AgAxisLineOptions { // The width in pixels of the axis line. width?: PixelSize; // The colour of the axis line. color?: CssColor; } type PixelSize = number type CssColor = string`
	`label` AgAxisLabelOptions	Configuration for the axis labels, shown next to the ticks. label: AgAxisLabelOptions; interface AgAxisLabelOptions { // The font style to use for the labels. fontStyle?: FontStyle; // The font weight to use for the labels. fontWeight?: FontWeight; // The font size in pixels to use for the labels. fontSize?: FontSize; // The font family to use for the labels fontFamily?: FontFamily; // Padding in pixels between the axis label and the tick. padding?: PixelSize; // The colour to use for the labels color?: CssColor; // The rotation of the axis labels in degrees. Note: for integrated charts the default is 335 degrees, unless the axis shows grouped or default categories (indexes). The first row of labels in a grouped category axis is rotated perpendicular to the axis line. rotation?: number; // If specified and axis labels may collide, they are rotated so that they are positioned at the supplied angle. This is enabled by default for category. If the `rotation` property is specified, it takes precedence. autoRotate?: boolean; // If autoRotate is enabled, specifies the rotation angle to use when autoRotate is activated. Defaults to an angle of 335 degrees if unspecified. autoRotateAngle?: number; // Avoid axis label collision by automatically reducing the number of ticks displayed. If set to `false`, axis labels may collide. avoidCollisions?: boolean; // Minimum gap in pixels between the axis labels before being removed to avoid collisions. minSpacing?: PixelSize; // Format string used when rendering labels. format?: string; // Function used to render axis labels. If `value` is a number, `fractionDigits` will also be provided, which indicates the number of fractional digits used in the step between ticks; for example, a tick step of `0.0005` would have `fractionDigits` set to `4` formatter?: (params: AgAxisLabelFormatterParams) => string \| undefined; } type FontStyle = 'normal' \| 'italic' \| 'oblique' type FontWeight = 'normal' \| 'bold' \| 'bolder' \| 'lighter' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900' type FontSize = number type FontFamily = string type PixelSize = number type CssColor = string interface AgAxisLabelFormatterParams { value: any; index: number; fractionDigits?: number; formatter?: (x: any) => string; }
	`gridStyle` AgAxisGridStyle[]	Configuration of the lines used to form the grid in the chart area. gridStyle: AgAxisGridStyle[]; interface AgAxisGridStyle { // The colour of the grid line. stroke?: CssColor; // Defines how the gridlines are rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels. lineDash?: PixelSize[]; } type CssColor = string type PixelSize = number
	`crossLines` AgCrossLineOptions[]	Add cross lines or regions corresponding to data values. crossLines: AgCrossLineOptions[]; interface AgCrossLineOptions { // Whether or not to show the cross line. enabled?: boolean; // Type of cross line to render. type: 'line' \| 'range'; // The data value at which the line should be positioned. This property is used if the crossLine type is `line`. value?: DataValue; // The range of values from the data used to display lines at a desired chart region. This property is only used for crossLine type `range`. range?: [ DataValue, DataValue ]; // The colour to use for the fill of the range. fill?: CssColor; // The opacity of the fill for the range. fillOpacity?: Opacity; // The colour of the stroke for the lines. stroke?: CssColor; // The width in pixels of the stroke for the lines. strokeWidth?: PixelSize; // The opacity of the stroke for the lines. strokeOpacity?: Opacity; // Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels. lineDash?: PixelSize[]; // Configuration for the crossLine label. label?: AgCrossLineLabelOptions; } type DataValue = any type CssColor = string type Opacity = number type PixelSize = number interface AgCrossLineLabelOptions { // Whether or not to show the cross line label. enabled?: boolean; // The text to show in the label. text?: string; // The font style to use for the label. fontStyle?: FontStyle; // The font weight to use for the label. fontWeight?: FontWeight; // The font size in pixels to use for the label. fontSize?: FontSize; // The font family to use for the label. fontFamily?: FontFamily; // Padding in pixels between the label and the edge of the crossLine. padding?: PixelSize; // The colour to use for the label. color?: CssColor; // The position of the crossLine label. position?: AgCrossLineLabelPosition; // The rotation of the crossLine label in degrees. rotation?: number; } type FontStyle = 'normal' \| 'italic' \| 'oblique' type FontWeight = 'normal' \| 'bold' \| 'bolder' \| 'lighter' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900' type FontSize = number type FontFamily = string type AgCrossLineLabelPosition = 'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'inside' \| 'insideLeft' \| 'insideRight' \| 'insideTop' \| 'insideBottom' \| 'insideTopLeft' \| 'insideBottomLeft' \| 'insideTopRight' \| 'insideBottomRight'
	`keys` string[]	string[]
	`thickness` PixelSize	If set to a non-zero value, the axis will have the specified thickness regardless of label size. `thickness: PixelSize; type PixelSize = number`

Category Axis

Properties available on the AgCategoryAxisOptions interface.

	`type` 'category'	'category'
	`paddingInner` Ratio	The size of the gap between the categories as a proportion, between 0 and 1. This value is a fraction of the “step”, which is the interval between the start of a band and the start of the next band. Default: `0.2` `paddingInner: Ratio; type Ratio = number`
	`paddingOuter` Ratio	The padding on the outside i.e. left and right of the first and last category. In association with `paddingInner`, this value can be between 0 and 1. Default: `0.3` `paddingOuter: Ratio; type Ratio = number`
	`groupPaddingInner` Ratio	This property is for grouped column/bar series plotted on a category axis. It is a proportion between 0 and 1 which determines the size of the gap between the bars or columns within a single group along the axis. Default: `0.2` `groupPaddingInner: Ratio; type Ratio = number`
	`tick` AgAxisCategoryTickOptions	Configuration for the axis ticks. tick: AgAxisCategoryTickOptions; interface AgAxisCategoryTickOptions { // The width in pixels of the axis ticks (and corresponding grid line). width?: PixelSize; // The length in pixels of the axis ticks. size?: PixelSize; // The colour of the axis ticks. color?: CssColor; // Array of values in axis units to display as ticks along the axis. // The values in this array must be compatible with the axis type. values?: any[]; // Minimum gap in pixels between tick lines. minSpacing?: number; // Maximum gap in pixels between tick lines. maxSpacing?: number; } type PixelSize = number type CssColor = string
	`crossLines` AgCrossLineOptions[]	Add cross lines or regions corresponding to data values. crossLines: AgCrossLineOptions[]; interface AgCrossLineOptions { // Whether or not to show the cross line. enabled?: boolean; // Type of cross line to render. type: 'line' \| 'range'; // The data value at which the line should be positioned. This property is used if the crossLine type is `line`. value?: DataValue; // The range of values from the data used to display lines at a desired chart region. This property is only used for crossLine type `range`. range?: [ DataValue, DataValue ]; // The colour to use for the fill of the range. fill?: CssColor; // The opacity of the fill for the range. fillOpacity?: Opacity; // The colour of the stroke for the lines. stroke?: CssColor; // The width in pixels of the stroke for the lines. strokeWidth?: PixelSize; // The opacity of the stroke for the lines. strokeOpacity?: Opacity; // Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels. lineDash?: PixelSize[]; // Configuration for the crossLine label. label?: AgCrossLineLabelOptions; } type DataValue = any type CssColor = string type Opacity = number type PixelSize = number interface AgCrossLineLabelOptions { // Whether or not to show the cross line label. enabled?: boolean; // The text to show in the label. text?: string; // The font style to use for the label. fontStyle?: FontStyle; // The font weight to use for the label. fontWeight?: FontWeight; // The font size in pixels to use for the label. fontSize?: FontSize; // The font family to use for the label. fontFamily?: FontFamily; // Padding in pixels between the label and the edge of the crossLine. padding?: PixelSize; // The colour to use for the label. color?: CssColor; // The position of the crossLine label. position?: AgCrossLineLabelPosition; // The rotation of the crossLine label in degrees. rotation?: number; } type FontStyle = 'normal' \| 'italic' \| 'oblique' type FontWeight = 'normal' \| 'bold' \| 'bolder' \| 'lighter' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900' type FontSize = number type FontFamily = string type AgCrossLineLabelPosition = 'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'inside' \| 'insideLeft' \| 'insideRight' \| 'insideTop' \| 'insideBottom' \| 'insideTopLeft' \| 'insideBottomLeft' \| 'insideTopRight' \| 'insideBottomRight'
	`thickness` PixelSize	If set to a non-zero value, the axis will have the specified thickness regardless of label size. `thickness: PixelSize; type PixelSize = number`

Number Axis

Properties available on the AgNumberAxisOptions interface.

	`type` 'number'	'number'
	`nice` boolean	If 'true', the range will be rounded up to ensure nice equal spacing between the ticks. Default: `true`
	`min` number	User override for the automatically determined min value (based on series data).
	`max` number	User override for the automatically determined max value (based on series data).
	`tick` AgAxisNumberTickOptions	Configuration for the axis ticks. tick: AgAxisNumberTickOptions; interface AgAxisNumberTickOptions { // The step value between ticks specified as a number. If the configured interval results in too many ticks given the chart size, it will be ignored. interval?: number; // The width in pixels of the axis ticks (and corresponding grid line). width?: PixelSize; // The length in pixels of the axis ticks. size?: PixelSize; // The colour of the axis ticks. color?: CssColor; // Array of values in axis units to display as ticks along the axis. // The values in this array must be compatible with the axis type. values?: any[]; // Minimum gap in pixels between tick lines. minSpacing?: number; // Maximum gap in pixels between tick lines. maxSpacing?: number; } type PixelSize = number type CssColor = string
	`crossLines` AgCrossLineOptions[]	Add cross lines or regions corresponding to data values. crossLines: AgCrossLineOptions[]; interface AgCrossLineOptions { // Whether or not to show the cross line. enabled?: boolean; // Type of cross line to render. type: 'line' \| 'range'; // The data value at which the line should be positioned. This property is used if the crossLine type is `line`. value?: DataValue; // The range of values from the data used to display lines at a desired chart region. This property is only used for crossLine type `range`. range?: [ DataValue, DataValue ]; // The colour to use for the fill of the range. fill?: CssColor; // The opacity of the fill for the range. fillOpacity?: Opacity; // The colour of the stroke for the lines. stroke?: CssColor; // The width in pixels of the stroke for the lines. strokeWidth?: PixelSize; // The opacity of the stroke for the lines. strokeOpacity?: Opacity; // Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels. lineDash?: PixelSize[]; // Configuration for the crossLine label. label?: AgCrossLineLabelOptions; } type DataValue = any type CssColor = string type Opacity = number type PixelSize = number interface AgCrossLineLabelOptions { // Whether or not to show the cross line label. enabled?: boolean; // The text to show in the label. text?: string; // The font style to use for the label. fontStyle?: FontStyle; // The font weight to use for the label. fontWeight?: FontWeight; // The font size in pixels to use for the label. fontSize?: FontSize; // The font family to use for the label. fontFamily?: FontFamily; // Padding in pixels between the label and the edge of the crossLine. padding?: PixelSize; // The colour to use for the label. color?: CssColor; // The position of the crossLine label. position?: AgCrossLineLabelPosition; // The rotation of the crossLine label in degrees. rotation?: number; } type FontStyle = 'normal' \| 'italic' \| 'oblique' type FontWeight = 'normal' \| 'bold' \| 'bolder' \| 'lighter' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900' type FontSize = number type FontFamily = string type AgCrossLineLabelPosition = 'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'inside' \| 'insideLeft' \| 'insideRight' \| 'insideTop' \| 'insideBottom' \| 'insideTopLeft' \| 'insideBottomLeft' \| 'insideTopRight' \| 'insideBottomRight'
	`thickness` PixelSize	If set to a non-zero value, the axis will have the specified thickness regardless of label size. `thickness: PixelSize; type PixelSize = number`

Log Axis

Properties available on the AgLogAxisOptions interface.

	`type` 'log'	'log'
	`nice` boolean	If 'true', the range will be rounded up to ensure nice equal spacing between the ticks. Default: `true`
	`min` number	User override for the automatically determined min value (based on series data). This value can be any non-zero number less than the configured `max` value.
	`max` number	User override for the automatically determined max value (based on series data). This value can be any non-zero number more than the configured `min` value.
	`base` number	The base of the logarithm used. Default: `10`
	`tick` AgAxisNumberTickOptions	Configuration for the axis ticks. tick: AgAxisNumberTickOptions; interface AgAxisNumberTickOptions { // The step value between ticks specified as a number. If the configured interval results in too many ticks given the chart size, it will be ignored. interval?: number; // The width in pixels of the axis ticks (and corresponding grid line). width?: PixelSize; // The length in pixels of the axis ticks. size?: PixelSize; // The colour of the axis ticks. color?: CssColor; // Array of values in axis units to display as ticks along the axis. // The values in this array must be compatible with the axis type. values?: any[]; // Minimum gap in pixels between tick lines. minSpacing?: number; // Maximum gap in pixels between tick lines. maxSpacing?: number; } type PixelSize = number type CssColor = string
	`crossLines` AgCrossLineOptions[]	Add cross lines or regions corresponding to data values. crossLines: AgCrossLineOptions[]; interface AgCrossLineOptions { // Whether or not to show the cross line. enabled?: boolean; // Type of cross line to render. type: 'line' \| 'range'; // The data value at which the line should be positioned. This property is used if the crossLine type is `line`. value?: DataValue; // The range of values from the data used to display lines at a desired chart region. This property is only used for crossLine type `range`. range?: [ DataValue, DataValue ]; // The colour to use for the fill of the range. fill?: CssColor; // The opacity of the fill for the range. fillOpacity?: Opacity; // The colour of the stroke for the lines. stroke?: CssColor; // The width in pixels of the stroke for the lines. strokeWidth?: PixelSize; // The opacity of the stroke for the lines. strokeOpacity?: Opacity; // Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels. lineDash?: PixelSize[]; // Configuration for the crossLine label. label?: AgCrossLineLabelOptions; } type DataValue = any type CssColor = string type Opacity = number type PixelSize = number interface AgCrossLineLabelOptions { // Whether or not to show the cross line label. enabled?: boolean; // The text to show in the label. text?: string; // The font style to use for the label. fontStyle?: FontStyle; // The font weight to use for the label. fontWeight?: FontWeight; // The font size in pixels to use for the label. fontSize?: FontSize; // The font family to use for the label. fontFamily?: FontFamily; // Padding in pixels between the label and the edge of the crossLine. padding?: PixelSize; // The colour to use for the label. color?: CssColor; // The position of the crossLine label. position?: AgCrossLineLabelPosition; // The rotation of the crossLine label in degrees. rotation?: number; } type FontStyle = 'normal' \| 'italic' \| 'oblique' type FontWeight = 'normal' \| 'bold' \| 'bolder' \| 'lighter' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900' type FontSize = number type FontFamily = string type AgCrossLineLabelPosition = 'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'inside' \| 'insideLeft' \| 'insideRight' \| 'insideTop' \| 'insideBottom' \| 'insideTopLeft' \| 'insideBottomLeft' \| 'insideTopRight' \| 'insideBottomRight'
	`thickness` PixelSize	If set to a non-zero value, the axis will have the specified thickness regardless of label size. `thickness: PixelSize; type PixelSize = number`

Time Axis

Properties available on the AgTimeAxisOptions interface.

	`type` 'time'	'time'
	`nice` boolean	If 'true', the range will be rounded up to ensure nice equal spacing between the ticks. Default: `true`
	`tick` AgAxisTimeTickOptions	Configuration for the axis ticks. tick: AgAxisTimeTickOptions; interface AgAxisTimeTickOptions { // A hint of how many ticks to use across an axis. // The axis is not guaranteed to use exactly this number of ticks, but will try to use a number of ticks that is close to the number given. // The following intervals from the `agCharts.time` namespace can be used: // `millisecond, second, minute, hour, day, sunday, monday, tuesday, wednesday, thursday, friday, saturday, month, year, utcMinute, utcHour, utcDay, utcMonth, utcYear`. // Derived intervals can be created by using the `every` method on the default ones. For example, `agCharts.time.month.every(2)` will return a derived interval that will make the axis place ticks for every other month. count?: any; // The step value between ticks specified as a TimeInterval or a number. If the configured interval results in dense ticks given the data domain, the ticks will be removed. interval?: any; // The width in pixels of the axis ticks (and corresponding grid line). width?: PixelSize; // The length in pixels of the axis ticks. size?: PixelSize; // The colour of the axis ticks. color?: CssColor; // Array of values in axis units to display as ticks along the axis. // The values in this array must be compatible with the axis type. values?: any[]; // Minimum gap in pixels between tick lines. minSpacing?: number; // Maximum gap in pixels between tick lines. maxSpacing?: number; } type PixelSize = number type CssColor = string
	`min` Date \| number	User override for the automatically determined min value (based on series data).
	`max` Date \| number	User override for the automatically determined max value (based on series data).
	`crossLines` AgCrossLineOptions[]	Add cross lines or regions corresponding to data values. crossLines: AgCrossLineOptions[]; interface AgCrossLineOptions { // Whether or not to show the cross line. enabled?: boolean; // Type of cross line to render. type: 'line' \| 'range'; // The data value at which the line should be positioned. This property is used if the crossLine type is `line`. value?: DataValue; // The range of values from the data used to display lines at a desired chart region. This property is only used for crossLine type `range`. range?: [ DataValue, DataValue ]; // The colour to use for the fill of the range. fill?: CssColor; // The opacity of the fill for the range. fillOpacity?: Opacity; // The colour of the stroke for the lines. stroke?: CssColor; // The width in pixels of the stroke for the lines. strokeWidth?: PixelSize; // The opacity of the stroke for the lines. strokeOpacity?: Opacity; // Defines how the line stroke is rendered. Every number in the array specifies the length in pixels of alternating dashes and gaps. For example, `[6, 3]` means dashes with a length of `6` pixels with gaps between of `3` pixels. lineDash?: PixelSize[]; // Configuration for the crossLine label. label?: AgCrossLineLabelOptions; } type DataValue = any type CssColor = string type Opacity = number type PixelSize = number interface AgCrossLineLabelOptions { // Whether or not to show the cross line label. enabled?: boolean; // The text to show in the label. text?: string; // The font style to use for the label. fontStyle?: FontStyle; // The font weight to use for the label. fontWeight?: FontWeight; // The font size in pixels to use for the label. fontSize?: FontSize; // The font family to use for the label. fontFamily?: FontFamily; // Padding in pixels between the label and the edge of the crossLine. padding?: PixelSize; // The colour to use for the label. color?: CssColor; // The position of the crossLine label. position?: AgCrossLineLabelPosition; // The rotation of the crossLine label in degrees. rotation?: number; } type FontStyle = 'normal' \| 'italic' \| 'oblique' type FontWeight = 'normal' \| 'bold' \| 'bolder' \| 'lighter' \| '100' \| '200' \| '300' \| '400' \| '500' \| '600' \| '700' \| '800' \| '900' type FontSize = number type FontFamily = string type AgCrossLineLabelPosition = 'top' \| 'left' \| 'right' \| 'bottom' \| 'topLeft' \| 'topRight' \| 'bottomLeft' \| 'bottomRight' \| 'inside' \| 'insideLeft' \| 'insideRight' \| 'insideTop' \| 'insideBottom' \| 'insideTopLeft' \| 'insideBottomLeft' \| 'insideTopRight' \| 'insideBottomRight'
	`thickness` PixelSize	If set to a non-zero value, the axis will have the specified thickness regardless of label size. `thickness: PixelSize; type PixelSize = number`

Next Up

Continue to the next section to learn more about overlays.

JavaScript Charts: Axes

Category Axis

Number Axis

Log Axis

Example: Number Axis vs Log Axis

Time Axis

Axis Title

Example: Axis Title

Axis Ticks

Tick Placement

Tick Min and Max Spacing

Tick Interval

Tick Values

Example: Axis Tick Placement

Tick Styling

Axis Labels

Label Rotation & Skipping

Label Formatting

Number Label Format String

Number Currency Format

Time Label Format String

Axis Grid Lines

Example: Grid Lines

Multiple axes in a single direction

Example: Multiple y-axes

Cross Lines

Example: Cross Lines

Axis API Reference

position

title

line

label

gridStyle

crossLines

keys

thickness

Category Axis

type

paddingInner

paddingOuter

groupPaddingInner

tick

crossLines

thickness

Number Axis

type

nice

min

max

tick

crossLines

thickness

Log Axis

type

nice

min

max

base

tick

crossLines

thickness

Time Axis

type

nice

tick

min

max

crossLines

thickness

Next Up

`position`

`title`

`line`

`label`

`gridStyle`

`crossLines`

`keys`

`thickness`

`type`

`paddingInner`

`paddingOuter`

`groupPaddingInner`

`tick`

`crossLines`

`thickness`

`type`

`nice`

`min`

`max`

`tick`

`crossLines`

`thickness`

`type`

`nice`

`min`

`max`

`base`

`tick`

`crossLines`

`thickness`

`type`

`nice`

`tick`

`min`

`max`

`crossLines`

`thickness`