SciChart.js JavaScript 2D Charts API > Axis APIs > Axis Label Formatting - LabelProvider API
Axis Label Formatting - LabelProvider API

All Axis Types include the AxisCore.labelProvider property, which to text-format axis and cursor labels.

Use a LabelProvider when you want to:

  • Format the text on axis labels such as changing the number of decimal places
  • Have fine grained control over Axis Text or Cursor Labels, depending on numeric (or date) values
  • Display strings on the Axis, e.g. “Bananas”, “Oranges”, “Apples” not “1”, “2”, “3”
  • Dynamically change the Axis Text Format as you zoom in or out or by data-value

In-Built LabelProviders in SciChart.js

SciChart.js has a built-in NumericLabelProvider which can be applied to axis. For example, if you wanted to format labels on the axis to two decimal places, you could use the following code:

Example Title
Copy Code
import {ENumericFormat, NumericLabelProvider} from "./LabelProvider/NumericLabelProvider";

const xAxis = new NumericAxis(webAssemblyContext);
xAxis.labelProvider = new NumericLabelProvider(ENumericFormat.Decimal_2);

The enum ENumericFormat contains options that are built-in, such as simple date and numeric formats. These essentially map to functions but you can provide your own.

Example Title
Copy Code
export enum ENumericFormat {
    /**
     * No format, return the string representation unchanged
     */
    NoFormat = "NoFormat",
    /**
     * Format as an integer
     */
    Decimal_0 = "Decimal_0",
    /**
     * Format as a floating-point number with 1 decimal place
     */
    Decimal_1 = "Decimal_1",
    /**
     * Format as a floating-point number with 2 decimal places
     */
    Decimal_2 = "Decimal_2",
    /**
     * Format as a floating-point number with 4 decimal places
     */
    Decimal_4 = "Decimal_4",
    /**
     * Format as a date in format DDMMYYYY
     */
    Date_DDMMYYYY = "Date_DDMMYYYY",
    /**
     * Format as a date in format DDMM
     */
    Date_DDMM = "Date_DDMM",
    /**
     * Format as a date in format HHMM
     */
    Date_HHMM = "Date_HHMM"
}

Creating your own LabelProviders

There are two ways to create a custom LabelProvider in SciChart.js. One is by inheriting LabelProvider as a TypeScript class and implementing your own Custom LabelProvider.


The second is to simply set a custom function on formatLabel or formatCursorLabel.

Let's look at both methods below.

Worked Example: Applying a LabelProvider function to format labels

This method is the easiest, and the most 'JavaScript'. Thanks to the object-based paradigm of JavaScript where every object is effectively collection of properties, you can override the label provider like this:

Example Title
Copy Code
import {NumericAxis} from "scichart/charting/Visuals/Axis/NumericAxis";

const xAxis = new NumericAxis(wasmContext);

// Override text formatting to format axis labels as 4-decimal places
xAxis.labelProvider.formatLabel = (dataValue => {
    return dataValue.toFixed(4);
});

// Override text formatting to format axis labels as a date. Assumes
// x-values in your data are unix timestamps
xAxis.labelProvider.formatLabel = (unixTimestamp : number) => {
        return new Date(unixTimestamp * 1000).toLocaleDateString("en-GB", {
           month: "numeric",
           year: "numeric",
           day: "numeric"
    });
};

This can work great in the majority of cases, but if you want finer-grained control over labels, say depending on zoom level or other requirements, then it may be better to create a custom LabelProvider class.

Worked Example: Creating a Custom LabelProvider Class

If you are using TypeScript, to create a custom label provider for the NumericAxis, we simply create a class that inherits LabelProvider, and override formatLabel() and optionally, formatCursorLabel()

There are also some additional functions called when the LabelProvider is attached to an axis, and when an axis draw pass begins. Use these to reset state or one-time setup if you have complex rules in the formatLabel function.

Example Title
Copy Code
/**
 * A CustomLabelProvider to format Axis Labels and Cursor / Tooltips for NumericAxis types
 */
export class CustomLabelProvider extends LabelProvider {
    constructor() {
        super();
    }
    /**
     * Called when the LabelProvider is attached to an Axis
     */
    public attachedToAxis(axis: AxisCore) {
        super.attachedToAxis(axis);
    }
    /**
     * Called once when an axis drawing pass begins. Use this method to do one-time setup
     */
    public onBeginAxisDraw(): void {
        // TODO: one-time setup at the beginning of
    }
    /**
     * Formats a data-value into a string for display on a cursor or tooltip
     */
    public formatCursorLabel(dataValue: number, formatString: string): string {
        return dataValue.toFixed(4);
    }
    /**
     * Formats a data-value into a string for display on the axis labels
     */
    public formatLabel(dataValue: number): string {
        return dataValue.toFixed(4);
    }
}

// Usage
const axis = new NumericAxis(wasmContext);
axis.labelProvider = new CustomLabelProvider();