format

Formats values.

Function parameters:
value: Number|Date

A value to be formatted.

Return Value: String

The value after formatting.

Default Value: undefined
Accepted Values: 'currency' | 'fixedPoint' | 'percent' | 'decimal' | 'exponential' | 'largeNumber' | 'thousands' | 'millions' | 'billions' | 'trillions' | 'longDate' | 'longTime' | 'longDateLongTime' | 'monthAndDay' | 'monthAndYear' | 'quarterAndYear' | 'shortDate' | 'shortTime' | 'shortDateShortTime' | 'second' | 'millisecond' | 'day' | 'month' | 'quarter' | 'year' | 'dayOfWeek' | 'hour' | 'minute'

This option accepts three types of values.

  • String
    One of the predefined formats (accepted by the type option) or a date format string (accepted by the raw option of the Globalize date formatter). For information on values accepted by the raw option, refer to the LDML documentation.

    NOTE
    The use of a custom date format requires Globalize libraries to be referenced within your application. For more information on using the Globalize library, refer to the Localization guide.
  • Function
    Specifies a custom format. A shortcut for the formatter option.

  • Object
    Allows you to configure the format in many aspects. Can have one of these two structures.

    // Uses a predefined format
    format: {
        type: String, // one of the predefined formats
        precision: Number, // the precision of values
        currency: String // a specific 3-letter code for the "currency" format
    }

    or

    // Specifies a custom format
    format: {
        formatter: Function, // a custom formatting function
        parser: Function // a parsing function for string values
    }

Instead of fields described in this section, you can use fields accepted by Globalize formatters. In this case, do not specify the type option. For example, you can use skeletons to format dates.

format: {
    skeleton: 'GyMMMd'
}

See the numberFormatter, currencyFormatter and dateFormatter documents for further information. Note that this approach might require additional CLDR modules not shipped with the DevExtreme package.

currency

Specifies the currency code for the 'currency' format.

Type: String
NOTE
The use of currency formats rather than 'USD' requires Globalize libraries to be referenced within your application. For more information on using Globalize library, refer to the Localization guide.

This option accepts a 3-letter code specified by ISO 4217 for each currency. Alternatively, you can set this option to 'default', in which case, the global default currency will be applied.

The global default currency is specified by the defaultCurrency field of the object returned by the DevExpress.config() method. By default, it is 'USD'. 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 culture 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 currency option.
See Also
  • format | precision - specifies the precision of values that have the currency format.

formatter

Specifies a custom format.

Type: function
Function parameters:
value: Number|Date

A value to be formatted.

Return Value: String

The value after formatting.

If none of the predefined formats meet your requirements, use this function to specify a custom format. 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
format: function (value) {
    // ...
    return formattedValue;
}
See Also
  • format | parser - parses string values into numeric or date-time values.

parser

Parses string values into numeric or date-time values.

Type: function
Function parameters:
value: String

A string value to be parsed.

Return Value: Number|Date

The value after parsing.

Along with the formatter function, parser participates in specifying a custom format. Use it 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, e.g., when the user enters a value into an editor.

precision

Specifies a precision for values of a numeric format.

Type: Number

This option applies when the type option has one of the following values.

  • 'currency'
  • 'fixedPoint'
  • 'percent'
  • 'decimal'
  • 'exponential'
  • 'largeNumber'
  • 'thousands'
  • 'millions'
  • 'billions'
  • 'trillions'

type

Specifies a predefined format.

Type: String
Accepted Values: 'currency' | 'fixedPoint' | 'percent' | 'decimal' | 'exponential' | 'largeNumber' | 'thousands' | 'millions' | 'billions' | 'trillions' | 'longDate' | 'longTime' | 'longDateLongTime' | 'monthAndDay' | 'monthAndYear' | 'quarterAndYear' | 'shortDate' | 'shortTime' | 'shortDateShortTime' | 'second' | 'millisecond' | 'day' | 'month' | 'quarter' | 'year' | 'dayOfWeek' | 'hour' | 'minute'

Depending on the values you need to format, choose one of the predefined formats. They can be divided into the following groups.

  • Numeric Formats
    'fixedPoint', 'percent', 'decimal', 'exponential', 'largeNumber', 'thousands', 'millions', 'billions', 'trillions'
  • Date-Time Formats
    'longDate', 'longTime', 'longDateLongTime', 'monthAndDay', 'monthAndYear', 'quarterAndYear', 'shortDate', 'shortTime', 'shortDateShortTime', 'millisecond', 'second', 'minute', 'hour', 'day', 'dayOfWeek', 'month', 'quarter', 'year'
  • Currency Formats
    'currency'

The 'fixedPoint', 'decimal' or 'currency' format can be paired with the 'largeNumber', 'thousands', 'millions', 'billions' or 'trillions' format using a space separator, e.g., 'fixedPoint thousands'.

If type is the only field you need to specify in the format object, assign the value of this field straight to the format option as shown below.

JavaScript
format: 'shortDate'
NOTE
The type option will not be applied if you have specified the formatter function.

When configuring a widget using ASP.NET MVC Wrappers, you can specify this option using the Format enum. This enum accepts the same values, but they start with an upper-case letter, for example, 'fixedPoint' becomes FixedPoint.

See Also
  • format | currency - specifies the currency code for the currency format.
  • format | precision - specifies the precision of values that have a numeric or currency format.