Formatters make it easy to customise the text shown for data across all chart elements, such as series labels, tooltips, and axes.
Global Formatter Copy Link
The chart level formatter is a callback called by all textual elements displaying data-based text. It should return a string to display, or undefined to fallback to the next available option.
The parameters provided to the callback differ based on whether the text is coming from a Number, Date or Category domain.
These properties provide enough context and information to tailor the formatting to your specific needs across different chart elements and scenarios.
These include:
type- whether the value is coming from a category, number, or date domain. This should not be confused with thetypeof the value - usetypeOfto determine that.value- the raw value to be formatted.source- the chart element, such asaxes-labelortooltip.property- the data visualisation property, such asx,y,size. These mirror the_Keyproperties.context- the user provided Context Object.- Properties to tie the value to the series and data used, such as
seriesId,boundSeries,domain,datum. - Date domains also include properties such as
unit,step,epoch.
See the API Reference for a full list.
Property Formatters Copy Link
For ease of use, the formatter can also be an object keyed by property, providing a separate callback for each data visualisation property. This allows specifying a format for every place this property is used.
{
formatter: {
x: (params) => {
const formatter = params.unit === 'year' ? yearFormatter : dateFormatter;
return formatter.format(params.value);
},
y: (params) => {
return `${magnitudeFormatter.format(params.value)} Mw`;
},
size: (params) => {
return deathsFormatter.format(params.value);
},
label: (params) => {
if (params.source === 'series-label') return params.datum.flag;
},
}
}
In this configuration:
xformats the x-axis values as a either a full date for the tooltip and crosshair, or year for the axis labels. It does this based on theunitvalue.yformats the y-axis values as values on the Richter scale, with one decimal place of precision.sizeformats the size values as a decimal number with no fractional digits.labelformats the label values removing additional information when it is a series label, otherwise returns the value as-is for the tooltip. It does this based on thesourcevalue.
The available properties are x, y, angle, radius, size, color, label, secondaryLabel, calloutLabel, and sectorLabel. These mirror the _Key properties
Inheritance and Precedence Copy Link
Each chart element has a formatter callback within its options, and these take precedence over the chart level formatter.
For example an axis label will be formatted as follows:
axes[].label.formatter- if provided and not returningundefined.- Chart
formatter- if provided and not returningundefined. - AG Chart defaults.
Additionally, if only an axes[].label.formatter is provided in the chart, the tooltip and crosshair formats will inherit based on this.
Format Strings Copy Link
A formatter can also be specified as a format string, which is a static string that represents a time or number format. This has less flexibility than the formatter function, but can be serialised.
{
formatter: {
x: "%b %Y",
y: "$#{0>6.2f}",
},
}
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, orZ.%%- 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.
symbol:$- The$currency symbol.#- For binary, octal, or hexadecimal notation, prefix by0b,0o, or0x, respectively.
zero- The0option enables zero-padding. Implicitly setsfillto0andalignto=.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 typesfand%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.