Skip to main content

Axis LabelProvider API Overview

All Axis Types include the AxisCore.labelProvider📘 property, which formats axis and cursor labels. Built in to SciChart.js are a number of labelProvider types, and you can even create your own.

The inheritance diagram for LabelProviders in SciChart.js looks like this:

All of these classes inherit LabelProviderBase2D. Below there is a mapping between which axis type has which labelprovider:

Axis TypeLabelProvider Type
NumericAxis and PolarNumericAxisNumericLabelProvider📘
DateTimeNumericAxisSmartDateLabelProvider📘
CategoryAxis and PolarCategoryAxisDateLabelProvider📘
LogarithmicAxisLogarithmicLabelProvider📘

We've included examples of how to format labels via the built-in label providers in the above articles. Click on NumericAxis or DateTimeNumericAxis above for more info and a code sample.

Applying a LabelProvider to an axis​

All axis (above) have a built-in LabelProvider. You can also apply a labelprovider to an axis with the following code:

SmartDate Formatting Example

import { CategoryAxis, SmartDateLabelProvider  } from "scichart";
sciChartSurface.xAxes.add(new CategoryAxis(wasmContext, {
         labelProvider: new SmartDateLabelProvider()
}));

If you have an axis where the date range can change as the user zooms, the SmartDateLabelProvider provides dynamic date labels which automatically adjust based on the axis range. You can also create custom dynamic labelproviders. See the rest of this article for steps how to do this.

LabelProvider & LabelProviderBase2D​

These are the base classes for all labelproviders in SciChart.js. Some of the properties they include can be found below.

The properties common to the LabelProviderBase2D / LabelProvider classes can be found in the TypeDoc API documentation📘.

There are many options to format axis labels in SciChart.js via the labelProvider.

In particular:

Setting LabelProvider properties​

LabelProvider properties can be set either on the labelProvider itself, or, in many cases can be set via the axis constructor options. The following code is equivalent:

// Set LabelProvider Properties in axis constructor options
sciChartSurface.xAxes.add(
    new NumericAxis(wasmContext, {
        // Enable decision labels with 4 significant figures
        labelFormat: ENumericFormat.Decimal,
        cursorLabelFormat: ENumericFormat.Decimal,
        labelPrecision: 4,
        labelPrefix: "$",
        labelPostfix: " USD"
    })
);

// Alternatively, set properties on the labelProvider itself
const yAxis = new NumericAxis(wasmContext);
yAxis.labelProvider.numericFormat = ENumericFormat.Decimal;
yAxis.labelProvider.cursorNumericFormat = ENumericFormat.Decimal;
yAxis.labelProvider.precision = 4;
yAxis.labelProvider.prefix = "$";
yAxis.labelProvider.postfix = " USD";
sciChartSurface.yAxes.add(yAxis);

This code sample configures label providers on the X & Y axis with exactly the same properties:

Overriding the formatLabel function​

Say you wanted further customisation in the axis labels than what axis.labelProvider.numericFormat📘 offers, you can start by overriding the formatLabel and formatCursorLabel functions.

Take a look at the code sample below:

// Format a label as hexadecimal by overriding formatLabel
const xAxis = new NumericAxis(wasmContext, {
    axisTitle: "X Axis with formatLabel",
    visibleRange: new NumberRange(0, 16),
    maxAutoTicks: 16
});
xAxis.labelProvider.formatLabel = dataValue => {
    return "0x" + dataValue.toString(16);
};
sciChartSurface.xAxes.add(xAxis);

The function formatLabel is overridden and called for each label on the xAxis. In this function we return a string format as hexadecimal to show how to customise labels even further.

Axis labels are formatted by formatLabel📘. Tooltip values are formated by formatCursorLabel📘. This allows you to have different label formats for tooltips and axis.

Custom LabelProviders​

See the following sections with worked examples on how to create custom label providers:

See Also​