Skip to main content

Labels

There are several different types of labels: axis labels, tick labels, and data labels.

Customizing axis labels

X axis tick labels are controlled by the data.labels array. This example chart uses the labels attribute to control the X axis display.

Y axis tick labels are automatically generated based on values unless you are using a categorical axis.

Scale labels

The axis.scaleLabel property controls the text that appears alongside the axis. Here's an example config:

Learn more about scale title configuration here.

Customizing tick labels

"Ticks" are the data markings that run along the axis. To format tick label, use the options.scales.<xAxes/yAxes>.ticks property.

There are many ways to customize tick values. For further reading, see:

Chart "tick" attributes

Attribute NameDescription
minMinimum value for the scale
maxMaximum value for the scale
suggestedMinSoft minimum value for the scale. The chart will use this minimum by default, but the minimum will be overridden if data value is less than suggested value.
suggestedMaxSoft maximum value for the scale. The chart will use this maximum by default, but the maximum will be overridden if data value is greater than suggested value.
callbackA Javascript function that is passed the value of the tick. The return value is displayed on the graph.
sampleSizeThe number of ticks to examine when deciding how many labels will fit. Setting a smaller value will render faster, but is less accurate in cases with large variance in label length. Defaults to sampling all ticks.
autoSkipIf true, automatically calculates how many labels can be shown and hides labels that will overlap. Labels will be rotated up to maxRotation before skipping. Turn autoSkip off to show all labels no matter what. Defaults to true.
autoSkipPaddingPadding between ticks on the horizontal axis when autoSkip is enabled. Defaults to 0
labelOffsetDistance in pixels to offset the label from the center point of the tick. Defaults to 0
maxRotationMaximum rotation for tick labels in degrees. Labels are rotated to make room for other labels. Only applies to horizontal scales. Defaults to 50
minRotationMinimum rotation for tick labels. Only applies to horizontal scales. Defaults to 0.
mirrorIf true, flips tick labels around the axis, displaying them inside the chart instead of outside. Only applicable to vertical scales. Defaults to false.
paddingPadding between tick labels and the axis, in pixels. Defaults to 0.

Below is an example that formats Y axis ticks as currency. The callback function localizes the currency, adding commas (or other delimeter) to the thousands place. You can use this technique to add percentage symbols and other label formats to your chart:

tickFormat: A helper plugin for custom Tick Labels

Writing a Javascript function can be a hassle. If your labels are not complex, the built-in tickFormat plugin allows you to apply common formatting needs without having to write Javascript. This can be simpler than writing the code yourself.

Use options.plugins.tickFormat to set options for formatting axis tick labels. The tickFormat object supports locale, prefix, suffix attributes, as well as all options supported by Javascript's Intl.NumberFormat.

tickFormat attributes

Attribute NameDescription
localeAn Intl.Locale string such as en-US (default), fr-FR, de-DE, en-GB. Full list here
prefixString to prepend to tick label
suffixString to append to tick label
styleThe formatting style to use. Default is decimal. decimal for plain number formatting currency for currency formatting percent for percent formatting unit for unit formatting
currencyThe currency to use in currency formatting. Possible values are the ISO 4217 currency codes, such as USD for the US dollar or EUR for the euro. Requires style=currency
unitThe unit to use in unit formatting, such as kilometers, megabyte, percent, etc. Must be a supported unit. Requires style=unit
minimumFractionDigitsThe minimum number of fraction digits to use. Useful to determine the number of decimals shown.
useGroupingtrue to display grouping separators in numbers, such as the thousands separator. false to disable. Defaults true.
More optionsNumber formatting is highly configurable. View Intl.NumberFormat documentation for the full list of options, including ability to control significant digits, scientific and engineering notation, and so on.

In this example, we add thousands commas to numbers on the numeric axis:

// ... Add commas or decimals
options: {
plugins: {
tickFormat: {
locale: 'en-US', // en-US is the default locale
useGrouping: true
}
}
}

This example will put a dollar symbol before each value and display two decimals of precision:

// ... Show as currency
options: {
plugins: {
tickFormat: {
style: 'currency',
currency: 'USD',
minimumFractionDigits: 2,
}
}
}

This tick formatter will append the letter "k" to every value:

// ... Add suffix
options: {
plugins: {
tickFormat: {
suffix: 'k';
}
}
}

Use tick callbacks to control visibility

ticks.callback is a powerful attribute that allows you to control whether the tick and its corresponding gridline appear.

Because ticks.callback is a Javascript function, it allows you to perform any logic based on the tick value and its index. The value returned by the callback is displayed on the chart. If the returned value is undefined, the tick is not drawn.

This callback hides the first and last ticks:

ticks: {
callback: (val, idx, ticks) => idx === 0 || idx === ticks.length - 1 ? undefined : val
}

Here we display every other tick:

ticks: {
callback: (val, idx) => idx % 2 === 0 ? val : undefined
}

And in this full example below, we display ticks only at specific values:

Data labels

QuickChart supports the Chart.js data labels plugin for adding custom data labels in your chart area. Labels can be added to an assortment of chart types, including bar, line, and scatter.

See this example configuration using datalabels.

Learn more:

Multi-line labels

All labels support the newline character, \n. Use this character to introduce a line break.

Annotation and label plugins

In order to extend annotation and labeling capabilities beyond Chart.js defaults, we provide three additional Chart.js plugins:

These plugins allow you to add various markup to your chart. Have a look at the documentation for each plugin to learn more about the possibilities.

Here's an example that uses Chart.js data labels and annotations:

Here's an example of a pie chart with outlabels, using the outlabeledPie type: