JavaScript ChartsAxis Labels

Axis labels provide clear identification and context for the data represented on each axis in a chart.

Collision Avoidance

AG Charts has a number of methods to avoid axis label collisions.

In this example:

Use the grab handle in the bottom right of the example to resize the chart. Observe how the labels behave with the different options applied.
The first row of buttons demonstrate all the rotation options.
The second row of buttons allows changing the length of the labels. This more easily shows the skipping behaviour.
The third row of buttons allows disabling the collision avoidance altogether.

Collision avoidance is enabled by default, to disable set label.avoidCollisions to false.

{
    label: {
        avoidCollisions: false,
    }
}

Rotation

Rotating axis labels allows fitting more labels into a smaller area, at the expense of readability.

Three rotation options are available:

No rotation.
Fixed rotation - labels are always rotated by the amount specified in the rotation property.
Automatic rotation - labels are rotated if any label will be wider than the gap between ticks.

Automatic rotation can be enabled or disabled using the autoRotate property. It is also possible to specify a rotation angle for the automatic rotation via the autoRotateAngle property.

Category axes have autoRotate enabled by default with a default autoRotateAngle of 335.

Skipping

Label skipping is performed automatically when there is a high likelihood of collisions between labels. Labels that would collide are not displayed.

A collision is defined as labels coming within 10 pixels of each other. This minimum gap allowed between the axis labels before skipping can be configured using the label.minSpacing property.

{
    label: {
        minSpacing: 20,
    }
}

If autoRotate is enabled, rotation will be attempted before label skipping applies.

Label Text Formatting

The label text is taken directly from the data. There are two ways to format this text, for example to show units next to values or to display number values to a certain precision.

This section discusses formatting the label text. See the Axis Intervals section to learn how to configure which labels are shown.

Formatter

The label.formatter callback allows maximum flexibility for controlling what appears in the labels.

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

In the above example:

The number axis uses a formatter to multiply by 100 and append '%' to all values.
The category axis uses a formatter to add '==' around the 'Windows' label only.

The formatter function receives a single params object which contains:

The raw value of the label (without any default formatting applied).
The index of the label in the data array.
The number of fractionDigits, if the value is a number.

It is called for each label and should return a string.

Format

The label.format property takes a static string representing a time or number format. This has less flexibility than the formatter, but can be serialised.

{
    label: {
        format: "%b %Y",
    }
}

In the above example:

The time axis uses a format to display the short month name and full year for all values.
The number axis uses a format to prepend a '$' and use 2 decimal places for all values. Shorter numbers are padding with '0'.

The syntax used in the format strings depends on the axis type.

The format string for time axis labels may contain the following directives, which reflect Python's strftime specification.

%a - Abbreviated weekday name.*
%A - Full weekday name.*
%b - Abbreviated month name.*
%B - Full month name.*
%c - 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 - 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]. Days preceding the first Sunday in the year in week 0
%V - ISO 8601 week number of the year as a decimal number [01, 53]. Week 1 is the first week where four or more days fall within the new year.
%w - Sunday-based weekday as a decimal number [0,6].
%W - Monday-based week of the year as a decimal number [00,53]. Days preceding the first Monday in the year are in week 0.
%x - Locale's date, such as %-m/%-d/%Y.*
%X - Locale's time, such as %-I:%M:%S %p.*
%y - Two-digit year as a decimal number [00,99].
%Y - Full year 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.

The % sign indicating a directive may be immediately followed by a padding modifier, otherwise no padding will be applied.

0 - zero-padding.
_ - space-padding.

The format string for number and log axis labels contain the following directives, which reflect 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 centred 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:
- $ - 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 minimum field width. If not specified, this will be determined by the content.
comma - The group separator, such as a comma for thousands.
precision - For types f and % determines the number of digits after the decimal point, otherwise determines the number of significant digits. Defaults to 6 for all types, or 12 if no type is supplied. Ignored for integer types.
~ - Trims insignificant trailing zeros across all format types.
type - Determines how the data should be presented:
- % - Multiply by 100, and display in decimal notation with a percent sign.
- b - Binary notation, rounded to integer.
- c - Display the integer as the corresponding unicode character.
- 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.

Formats should be wrapped with #{} if included within a string so that it's clear where the number format begins and ends. For example: I'm #{0>2.0f} years old.

Next Up

Continue to the next section to learn about Grid Lines.

Getting started

Core features

Specialised Charts

Series

Gauges