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

dxPieChart

dxCircularGauge and dxLinearGauge

dxBarGuage

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 displays a numeric value, you can set a particular format ("currency", "percent", etc.) for this numeric value using the format option. Choose an appropriate format from a set of the predefined numeric formats. In addition, you can set a precision for numeric values using the precision option. The following configuration makes labels display values rounded up to the nearest hundredth.

JavaScript
var data = [
    { quarter: 'QI', quantity: 26.252 },
    { quarter: 'QII', quantity: 26.5 },
    { quarter: 'QIII', quantity: 26.375 },
    { quarter: 'QIV', quantity: 25.75 }
];

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

Format Precision

If a label displays a date-time value, use the format option to specify a 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 data = [
    { 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: data,
    argumentAxis: {
        label: {
            format: 'monthAndDay',
            // ...
        }
    },
    // ...
};

Date-Time Format

Alternatively, you can specify a custom format using format tokens from the Globalize JavaScript library. In the following code, these tokens are used to specify a format for axis labels.

JavaScript
var chartOptions = {
    dataSource: dataSource,
    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. To prevent this, set a custom tick interval. See the Axis Ticks Arrangement topic for more information.

Provide a Custom Text

If the capabilities of the format option do not meet your requirements, use the customizeText option to provide a custom text. Implement a function that returns the required text and assign it to this option. Within this function, you can use the value to be shown or its formatted version (if you have specified the format and precision option). To access them, use the value and valueText fields of the function's parameter.

JavaScript
var data = [
    { quarter: 'QI', quantity: 26.252 },
    { quarter: 'QII', quantity: 26.5 },
    { quarter: 'QIII', quantity: 26.375 },
    { quarter: 'QIV', quantity: 25.75 }
];

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

Custom Text

In the dxChart, dxPieChart and dxPolarChart widgets, the parameter of the customizeText function has an extended list of fields. For example, you can access the argument of a point using the argument field. To access its formatted equivalent, use the argumentText field. These fields differ only if you have specified the argumentFormat and argumentPrecision options.

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

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

Custom Text with Argument Value

Available Formats

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

Numeric Formats

DevExtreme ChartJS AvailableFormats

NOTE: Formats from the left column can be combined with the formats from the right column. For example, 1000000 with the "currency millions" format will produce "$1M".

Date-Time Formats

  • 'longDate' - "Thursday, January 01, 1970"
  • 'longTime' - "12:00:00 AM"
  • 'monthAndDay' - "January 01"
  • 'monthAndYear' - "1970 January"
  • 'quarterAndYear' - "QI 1970"
  • 'shortDate' - "1/25/1970"
  • 'shortTime' - "12:00 AM"
  • 'millisecond' - "010"
  • 'day' - "01"
  • 'month' - "January"
  • 'quarter' - "QI"
  • 'year' - "1970"

Custom Format

In addition to the predefined formats above, you can assign a custom format using tokens from the Globalize library. Moreover, the ChartJS library supplies format tokens to display a date as a quarter value. To use these tokens, assign one of them to the format option of a customizable text element. Assume that a date belongs to the first quarter. Then, the result of using format tokens will be the following.

  • "q" - I
  • "qq" - QI
  • "Q" - 1
  • "QQ" - Q1