Data Formatting

In the widgets provided by the DevExtreme Data Visualization library, you can easily customize the automatically generated text for the following widget elements.

Chart and PolarChart

PieChart

TreeMap

CircularGauge and LinearGauge

BarGuage

RangeSelector

Bullet and Sparkline

For this purpose, the widgets provide a uniform set of options. No matter where you need to customize text, you always have the format and customizeText (or customizeTooltip for tooltips) options.

Also, DevExtreme widgets provide a set of predefined formats that cover most cases of applying a format. These formats can be divided into three groups.

  • Numeric Formats
  • Date-Time Formats
  • Currency Formats

Moreover, you can specify a custom format. See the following topics for detailed information on each case.

Numeric Formats

DevExtreme ChartJS AvailableFormats

NOTE
Formats from the left column can be paired with formats from the right column using a space separator, e.g., 'fixedPoint thousands'.

To set a numeric format, use the format.type option. Also, you can apply a precision to numeric values using the format.precision option. For example, the following configuration makes Chart's series point 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: {
                type: 'fixedPoint',
                precision: 2
            }
        }
    }
};

DevExpress HTML5 DataVisualizationWidgets Chart Format Precision

The format option also accepts strings. Use this capability as a shortcut for specifying a predefined format.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: 'fixedPoint'
    }
};

Alternatively, you can use a native formatter of the Globalize library. In this case, the format option accepts an object whose fields are the same as the options passed to the numberFormatter.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            // ...
            minimumIntegerDigits: 1
        }
    }
};

Note that you must not set the type option if you use a Globalize formatter. Also, this approach might require additional CLDR modules not shipped with the DevExtreme package.

Date-Time Formats

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

To set a date-time format, assign one of the values above to the format.type option. For example, the following code applies the 'monthAndDay' format to Chart's argument axis labels.

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: {
                type: 'monthAndDay'
            }
        }
    }
};

Date-Time Format

The format option also accepts strings. Use this capability as a shortcut for specifying a predefined format.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: 'monthAndDay'
    }
};

Alternatively, you can use a native formatter of the Globalize library. In this case, the format option accepts an object whose fields are the same as the options passed to the dateFormatter.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            skeleton: "GyMMMd"
        }
    }
};

Note that you must not set the type option if you use a Globalize formatter. Also, this approach might require additional CLDR modules not shipped with the DevExtreme package.

Currency Formats

To set a currency format, assign 'currency' to the format.type option.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            type: 'currency'
        }
    }
};

This setting applies the global default currency - 'USD'. It is specified by the defaultCurrency field of the object returned by the DevExpress.config() method. To change it, use the following code.

JavaScript
DevExpress.config({ defaultCurrency: 'EUR' });

To use any currency that differs from USD, follow these steps.

  1. Get the currencies.json file that corresponds to your locale from one of the folders here.
  2. Load the contents of this file in your app using one of the methods described here.
  3. Assign the 3-letter code of the needed currency to the format.currency option.

    JavaScript
    var widgetOptions = {
        // ...
        customizableElement: {
            format: {
                type: 'currency',
                currency: 'EUR'
            }
        }
    };

Additionally, you can specify the precision of currency values using the format.precision option.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            // ...
            type: 'currency',
            precision: 2
        }
    }
};

If you do not need to change neither the currency nor the precision field, assign 'currency' straight to the format option. This setting will apply the global default currency.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: 'currency'
    }
};

Alternatively, you can use a native formatter of the Globalize library. In this case, the format option accepts an object whose fields are the same as the options passed to the currencyFormatter.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            currency: 'EUR',
            style: 'name'
        }
    }
};

Note that you must not set the type option if you use a Globalize formatter. Also, this approach might require additional CLDR modules not shipped with the DevExtreme package.

Custom Format

If none of the predefined formats meet your requirements, specify a custom format using the formatter function. This function accepts the original value as the parameter and returns a formatted string.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            formatter: function (originalValue) {
                // ...
                return formattedString;
            }
        }
    }
};

In addition, you can implement the parser function to parse numbers or dates presented as strings into the correct format. This function may be called internally by the widget at different points of your application's lifetime.

JavaScript
var widgetOptions = {
    // ...
    customizableElement: {
        format: {
            // ...
            parser: function (stringToParse) {
                // ...
                return valueWithCorrectFormat;
            }
        }
    }
};

If formatter is the only field that you need to specify in the format object, assign the function straight to the format option as shown below.

JavaScript
var widgetOptions = { // ... customizableElement: { format: function (originalValue) { // ... return formattedString; } } };
JavaScript

Customize Text

When you need to customize text after (or instead of) applying a format, use the customizeText function. This function returns the final text. Its parameter contains data about the element whose text is being customized. The actual contents of this parameter depend on the element. For example, the following code customizes the text of the Chart's value axis labels after applying a 'fixedPoint' format.

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: {
                type: 'fixedPoint',
                precision: 2
            },
            customizeText: function (data) {
                return data.valueText + 'ml' ;
            }
        }
    }
};

Custom Text

When providing a custom text for tooltips, use the customizeTooltip function instead of customizeText. This function must return an object wherein the required text is assigned to the 'text' field. In the following code, the customizeTooltip function combines the formatted value and argument of a point.

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

Custom Text with Argument Value