Data Formatting

With the widgets provided by the DevExtreme data visualization library, you can easily customize the automatically generated text for the following widget elements.

dxChart and dxPolarChart

dxCircularGauge and dxLinearGauge

dxBarGuage

dxPieChart

dxRangeSelector

dxBullet and dxSparkline

dxVectorMap

For this purpose, a common options template is provided. No matter where you need to customize text, you have the format, precision and customizeText (or customizeTooltip for tooltips) options. The topics below summarize the capabilities that these options provide.

Format Text

If a label represents a numeric value, you can set a particular format ("currency", "percent", etc.) for presenting a numeric value. For this purpose, use the format option. Choose an appropriate format within the set of the predefined numeric formats.

JavaScript
var dataSource = [
    { date: new Date(1994,2,3), quantity: 26.25 },
    { date: new Date(1994,2,4), quantity: 26.50 },
    { date: new Date(1994,2,5), quantity: 26.375 },
    { date: new Date(1994,2,6), quantity: 25.75 }
];

var chartOptions = {
    dataSource: dataSource,
    series: [{
        //...
        label: {
            format: 'fixedPoint',
            //...
        }
    }]
};

Numeric Format

In addition, you can set the required precision for a numeric value. For this purpose, use the precision option.

JavaScript
$(function () {
    var chartOptions = {
        series: [{
            //...
            label: {
                format: 'fixedPoint',
                precision: 2,
                //...
            }
        }]
    });
});

Format Precision

If a label represents a date-time value, use the format option to set a particular date-time format. You can set one of the predefined date-time formats. The following example demonstrates the use of the monthAndDay format.

JavaScript
var dataSource = [
    { date: new Date(1994,2,3), quantity: 26.25 },
    { date: new Date(1994,2,4), quantity: 26.50 },
    { date: new Date(1994,2,5), quantity: 26.375 },
    { date: new Date(1994,2,6), quantity: 25.75 },
];

$(function () {
    var chartOptions = {
        dataSource: dataSource,
        argumentAxis: {
            label: {
                format: 'monthAndDay'
            }
        }
    });
});

Date-Time Format

In addition to the predefined formats, you can set a custom format using format tokens from the Globalize JavaScript library.

JavaScript
$(function () {
    var chartOptions = {
        argumentAxis: {
            label: {
                format: 'MM/d'
            }
        }
    });
});

Custom Date-Time Format

NOTE
When applying a format to automatically generated ticks, you may get repeated ticks or other side effects. In this instance, regenerate ticks manually by setting a custom tick interval. To learn how to do this, refer to the Axis Ticks Arrangement topic.

Provide a Custom Text

If value formatting is not appropriate for your task, and you need to provide a custom text, use the customizeText option. Assign a function that returns the required text. Within this function, you can use the value to be shown or its formatted version if you specified the format and precision option (see Format Text). These values can be accessed using the value and valueText fields of the object passed as the function's parameter or the this object.

JavaScript
var dataSource = [
    { date: new Date(1994,2,3), quantity: 26.25 },
    { date: new Date(1994,2,4), quantity: 26.50 },
    { date: new Date(1994,2,5), quantity: 26.375 },
    { date: new Date(1994,2,6), quantity: 25.75 }
];

var chartOptions = {
    dataSource: dataSource,
    // ...
    valueAxis: {
        label: {
            format: 'fixedPoint',
            precision: 2,
            customizeText: function () {
                return this.valueText + 'ml' ;
            }
        }
    }
};

Custom Text

When providing a custom text for labels in a chart, gauge or range selector, the object passed as the customizeText function's parameter has an extended list of fields. For example, you can use the argument value raw or, if you specified the argumentFormat and argumentPrecision options, in a formatted form. This value can be accessed using the argument or argumentText field of the object passed as the function's parameter or the this object.

When providing a custom text for tooltips, use the customizeTooltip option instead of customizeText. Assign a callback function to this option. This function should return an object, in which a required text should be assigned to the 'text' field.

JavaScript
$(function () {
    var chartOptions = {
        // ...
        tooltip: {
            enabled: true,
            format: 'fixedPoint',
            precision: 2,
            argumentFormat: 'MM/d',
            customizeTooltip: function () {
                return { 
                    text: this.valueText + ' on ' + this.argumentText
                };
            }
        }
    });
});

Custom Text with Argument Value

Available Formats

This topic lists all the formats that you can apply to a label using the format option (see Format Text).

Numeric Formats

  • 'currency' - displays a value as currency
  • 'currency largeNumber' – a value is divided by a number (one thousand, one million, one billion or one trillion) so that the value is less than a thousand; then letter 'K', 'M', 'B' or 'T' is added and the 'currency' format is applied
  • 'currency thousands' - a value is divided by one thousand, the letter 'K' is added and the 'currency' format is applied
  • 'currency millions' - a value is divided by one million, the letter 'M' is added and the 'currency' format is applied
  • 'currency billions' - a value is divided by one billion, the letter 'B' is added and the 'currency' format is applied
  • 'currency trillions' - a value is divided by one trillion, the letter 'T' is added and the 'currency' format is applied

NOTE: If you set a currency format, values will be formatted according to the settings specified for the current culture in the globalize library. To provide a custom 'currency' format, use the customizeText option instead.

  • 'fixedPoint' - displays a value as a real numeric value with a specified number of digits for the fractional part and an optional negative sign
  • 'fixedPoint largeNumber' - a value is divided by a number (one thousand, one million, one billion or one trillion) so that the value is less than a thousand; then letter 'K', 'M', 'B' or 'T' is added and the 'fixedPoint' format is applied
  • 'fixedPoint thousands' - a value is divided by one thousand, the letter 'K' is added and the 'fixedPoint' format is applied
  • 'fixedPoint millions' - a value is divided by one million, the letter 'M' is added and the 'fixedPoint' format is applied
  • 'fixedPoint billions' - a value is divided by one billion, the letter 'B' is added and the 'fixedPoint' format is applied
  • 'fixedPoint trillions' - a value is divided by one trillion, the letter 'T' is added and the 'fixedPoint' format is applied
  • 'decimal' – displays a value as an integer with an optional negative sign
  • 'decimal largeNumber' - a value is divided by a number (one thousand, one million, one billion or one trillion) so that the value is less than a thousand; then letter 'K', 'M', 'B' or 'T' is added and the 'decimal' format is applied
  • 'decimal thousands' - a value is divided by one thousand, the letter 'K' is added and the 'decimal' format is applied
  • 'decimal millions' - a value is divided by one million, the letter 'M' is added and the 'decimal' format is applied
  • 'decimal billions' - a value is divided by one billion, the letter 'B' is added and the 'decimal' format is applied
  • 'decimal trillions' - a value is divided by one trillion, the letter 'T' is added and the 'decimal' format is applied
  • 'largeNumber' - a value is divided by a number (one thousand, one million, one billion or one trillion) so that the value is less than a thousand; then letter 'K', 'M', 'B' or 'T' is added and the 'fixedPoint' format is applied
  • 'thousands' - a value is divided by one thousand, the letter 'K' is added and the 'fixedPoint' format is applied
  • 'millions' - a value is divided by one million, the letter 'M' is added and the 'fixedPoint' format is applied
  • 'billions' - a value is divided by one billion, the letter 'B' is added and the 'fixedPoint' format is applied
  • 'trillions' - a value is divided by one trillion, the letter 'T' is added and the 'fixedPoint' format is applied
  • 'percent' - a value is multiplied by 100 and displayed with a percent symbol
  • 'exponential' – displays a value with an exponential notation

NOTE: You can set a precision for a label value when the 'fixedPoint', 'exponential', 'currency' or 'percent' format is applied. Use the precision and argumentPrecision options to do this.

Date-Time Formats

  • 'longDate'
  • 'longTime'
  • 'monthAndDay'
  • 'monthAndYear'
  • 'quarterAndYear'
  • 'shortDate'
  • 'shortTime'
  • 'millisecond'
  • 'day'
  • 'month'
  • 'quarter'
  • 'year'

Custom Format

In addition to the predefined formats above, you can assign a custom format. Use format tokens from the Globalize JavaScript library to do this. In addition, the ChartJS library supplies format tokens for displaying a date as a quarter value. The following is a list of format tokens that are available for custom formatting.

  • Format tokens from the Globalize library
  • q - displays a quarter as a Roman numeral
  • qq - displays a quarter as a Roman numeral with the Q prefix
  • Q - displays a quarter as an Arabic numeral
  • QQ - displays a quarter as an Arabic numeral with the Q prefix