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 Name | Description |
|---|---|
| min | Minimum value for the scale |
| max | Maximum value for the scale |
| suggestedMin | Soft 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. |
| suggestedMax | Soft 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. |
| callback | A Javascript function that is passed the value of the tick. The return value is displayed on the graph. |
| sampleSize | The 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. |
| autoSkip | If 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. |
| autoSkipPadding | Padding between ticks on the horizontal axis when autoSkip is enabled. Defaults to 0 |
| labelOffset | Distance in pixels to offset the label from the center point of the tick. Defaults to 0 |
| maxRotation | Maximum rotation for tick labels in degrees. Labels are rotated to make room for other labels. Only applies to horizontal scales. Defaults to 50 |
| minRotation | Minimum rotation for tick labels. Only applies to horizontal scales. Defaults to 0. |
| mirror | If true, flips tick labels around the axis, displaying them inside the chart instead of outside. Only applicable to vertical scales. Defaults to false. |
| padding | Padding 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 Name | Description |
|---|---|
| locale | An Intl.Locale string such as en-US (default), fr-FR, de-DE, en-GB. Full list here |
| prefix | String to prepend to tick label |
| suffix | String to append to tick label |
| style | The formatting style to use. Default is decimal. decimal for plain number formatting currency for currency formatting percent for percent formatting unit for unit formatting |
| currency | The 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 |
| unit | The unit to use in unit formatting, such as kilometers, megabyte, percent, etc. Must be a supported unit. Requires style=unit |
| minimumFractionDigits | The minimum number of fraction digits to use. Useful to determine the number of decimals shown. |
| useGrouping | true to display grouping separators in numbers, such as the thousands separator. false to disable. Defaults true. |
| applyToDataLabels | whether to apply the formatter to datalabels on the chart |
| axisID | which axis to apply the formatter to (default: all numeric axes) |
| More options | Number 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:
Forcing ticks to display
To ensure that all tick labels are displayed on your chart, set the autoSkip property to false in the ticks configuration of your axes.
By default, Chart.js will automatically calculate how many labels can be shown without overlap, and will skip labels as necessary. The autoSkip property disables this behavior.
{
// ... scale options ...
ticks: {
autoSkip: false
}
}
More details about autoSkip and other tick configurations can be found in the Chart.js documentation.
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.
Examples
Here's an example configuration that displays labels above each bars using the datalabels plugin:
The display and formatter properties of the datalabels plugin are very powerful. In this next example, we use them to dynamically show/hide the labels and alter the text of the label. We hide any labels that aren't the first, last, min, or max value:
Labels for pie and doughnut charts
Pie and doughnut charts rely heavily on datalabels. By default, the tickFormat plugin applies to datalabels on charts that do not have any numeric axes. See more on how to customize labels on pie and doughnut charts.
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:
- Data Labels - chartjs-plugin-datalabels
- Annotations - chartjs-plugin-annotation
- Outlabels - chartjs-plugin-piechart-outlabels
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: