A newer version of this page is available. Switch to the current version.

jQuery Common - Object Structures - format

Formats values.

import { Format } from "devextreme/localization"
Type:

Object

|

String

|

Function

Function parameters:
value:

Number

|

Date

The value to be formatted.

Return Value:

String

The value after formatting.

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

This property accepts three types of values:

  • String
    A predefined format or custom format string.

  • Function
    Applies a custom format to a value and returns this value as a string. A shortcut for the formatter property.

  • Object
    Allows you to configure the format. Can have one of the following structures:

    DevExtreme
    // 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

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

    You can specify the Intl NumberFormat's and DateTimeFormat's options parameter fields:

    Intl
    format: { year: "2-digit", month: "narrow", day: "2-digit" }
    === or ===
    format: { style: "currency", currency: "EUR", useGrouping: true }

    If you use Globalize, you can use the fields that the numberFormatter, currencyFormatter, and dateFormatter accept instead of the fields described in this section. For example, you can use skeletons to format dates. Note that this approach can require additional CLDR modules not shipped with the DevExtreme package.

    Globalize
    format: { skeleton: 'GyMMMd' }
    NOTE
    Depending on the object structure, the format utility chooses the mechanism to use: DevExtreme internal, Intl, or Globalize. If you mix properties from different zones (DevExtreme, Intl, or Globalize) in an object, the result can be unpredictable.

View Demo

currency

Specifies a 3-letter ISO 4217 code for currency. Applies only if the type is "currency".

Type:

String

Alternatively, you can set the globalConfig.defaultCurrency property to apply the same currency to all DevExtreme components.

See Also

formatter

A function that converts numeric or date-time values to a string.

Type:

Function

Function parameters:
value:

Number

|

Date

The 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 property as shown below.

JavaScript
format: function (value) {
    // ...
    return formattedValue;
}
IMPORTANT
If you allow users to edit the formatted value, implement the parser function to convert the value back to a number or date and time.

parser

Parses string values into numeric or date-time values. Should be used with formatter or one of the predefined formats.

Type:

Function

Function parameters:
value:

String

The string value to be parsed.

Return Value:

Number

|

Date

The value after parsing.

A UI component calls this function internally, for example, when a user enters a value. The following code gives an example of the formatter and parser functions which turns dates into strings, and parses strings back into dates, respectively.

JavaScript
formatter: function (date) {
    const day = date.getDate();
    const month = date.getMonth() + 1;
    const year = date.getFullYear();

    return `${day}.${month}.${year}`;
},
parser: function (e) {
    const parts = e.split(".");
    const day = Number(parts[0]);
    const month = Number(parts[1] - 1);
    const year = Number(parts[2]);

    return new Date(year, month, day);
}

precision

Specifies a precision for values of numeric or currency format types.

Type:

Number

View Demo

NOTE

When you specify a precision for a "decimal" format type, it applies to the integer part instead of the fractional part of a decimal number:

JavaScript
const decimalNumber = 1.234;

format: {
    type: "decimal",
    precision: 2
}
// 01.234

To apply the precision to the fractional part, use the "fixedPoint" format type:

JavaScript
const decimalNumber = 1.234;

format: {
    type: "fixedPoint",
    precision: 2
}
// 1.23

type

Specifies a predefined format. Does not apply if you have specified the formatter function.

Type:

String

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

Depending on the values you need to format, you can choose one of the following predefined formats:

Numeric Formats

JavaScript
const smallNumber = 1.2345;

type: "fixedPoint" // 1
type: "decimal" // 1.2345
type: "percent" // 123%
type: "currency" // $1
JavaScript
const largeNumber = 1000000000;

type: "exponential" // 1.0E+9
type: "thousands" // 1,000,000K
type: "millions" // 1,000M
type: "billions" // 1B
type: "trillions" // 0T
type: "largeNumber" // 1B (uses "thousands", "millions", "billions", or "trillions", depending on the value)
NOTE
  • Set the precision property to show fractional numbers.

  • Set the currency property to use a currency other than USD. Alternatively, you can set the globalConfig.defaultCurrency property to apply the same currency to all DevExtreme components.

  • The "fixedPoint", "decimal", and "currency" format types can be paired with "largeNumber", "thousands", "millions", "billions", and "trillions", for example: "fixedPoint thousands".

  • Editor components, such as NumberBox, do not support large number formats. If you want to apply these formats, you can implement the formatter and parser functions or specify a custom format string.

Date-Time Formats

JavaScript
const date = new Date(2021, 6, 15, 20, 45, 34);

type: "longDate" // Thursday, July 15, 2021
type: "longTime" // 8:45:34 PM
type: "longDateLongTime" // Thursday, July 15, 2021, 8:45:34 PM
type: "monthAndDay" // July 15
type: "monthAndYear" // July 2021
type: "quarterAndYear" // Q3 2021
type: "shortDate" // 7/15/2021
type: "shortTime" // 8:45 PM
type: "shortDateShortTime" // 7/15/2021, 8:45 PM
type: "millisecond" // 000
type: "second" // 34
type: "minute" // 45
type: "hour" // 20
type: "day" // 15
type: "dayOfWeek" // Thursday
type: "month" // July
type: "quarter" // Q3
type: "year" // 2021

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

JavaScript
format: "shortDate"

View Demo

See Also

useCurrencyAccountingStyle

Specifies whether to apply the accounting style to formatted numbers of the currency type.

Type:

Boolean

Default Value: true

The accounting style adds parentheses to negative numbers instead of the minus sign. To disable the accounting style in the component and display formatted numbers of the currency type with the minus sign, set this property to false.

format({
    type: "currency",
    useCurrencyAccountingStyle: false 
});

If you do not specify this property, the defaultUseCurrencyAccountingStyle global configuration setting is in effect. The useCurrencyAccountingStyle property has priority over the global setting.

How to Override the defaultUseCurrencyAccountingStyle