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

jQuery Common - Object Structures - format

Formats values.

Type:

String

|

Function

|

Object

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 option accepts three types of values:

  • String
    One of the predefined formats (see the type option) or a format string. The built-in localization engine supports the following characters. You can specify different formats by repeating these characters.

    Numeric Formats

    Format character Description
    0 A digit. Displays '0' if it is not specified in the UI.
    # A digit or nothing. One symbol represents several integer digits, but only one decimal digit.
    For example, "#.#" represents "123.4", but not "123.45".
    . A decimal separator.
    Displayed according to the decimalSeparator or the set locale if you use Intl or Globalize.
    , A group separator.
    Displayed according to the thousandsSeparator or the set locale if you use Intl or Globalize.
    % The percent sign. Divides the input value by 100.
    If it is enclosed in single quotes ('%'), it only adds this sign to the input value.
    ; Separates positive and negative numbers. If there is no explicit negative format, a positive number receives the "-" prefix.
    Other characters Any character. Should be placed only at the format string's beginning or end.
    You can use the special characters above as well (in single quotation marks).

    Date-Time Formats

    Format character Description
    y A calendar year.
    Q A quarter number or name.
    Available combinations with example: "Q" - "2", "QQ" - "02", "QQQ" - "Q2" and "QQQQ" - "2nd quarter".
    M A month number or name.
    Available combinations with example: "M" - "9", "MM" - "09", "MMM" - "Sep", "MMMM" - "September", "MMMMM" - "S".
    d A month day.
    E A week day name.
    Available combinations with example: "E", "EE" or "EEE" - "Tue", "EEEE" - "Tuesday", "EEEEE" - "T".
    a A day period (am or pm).
    h An hour. From 1 to 12.
    H An hour. From 0 to 23.
    m A minute.
    s A second.
    S A fractional second.
    NOTE
    Reference the Globalize library in your application to use other numeric or datetime format characters.
  • Function
    Specifies a custom format. A shortcut for the formatter option.

  • Object
    Allows you to configure the format. 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
    }

    If you use Devextreme-Intl, you can specify the Intl NumberFormat's and DateTimeFormat's options parameter fields:

    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 accepted by numberFormatter, currencyFormatter, and dateFormatter instead of the fields described in this section. For example, you can use skeletons to format dates. Note that this approach might require additional CLDR modules not shipped with the DevExtreme package.

    format: { skeleton: 'GyMMMd' }

View Demo

currency

Specifies the currency code. Applies only if type is "currency".

Type:

String

NOTE
Reference Globalize or Intl if you specify a currency code other than "USD".

This option accepts a 3-letter code specified by ISO 4217 for each currency. If you use Intl, just assign the code to this option. If you use Globalize, do the following:

  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 this option.

Alternatively, you can assign "default" to this option, in which case, the global default currency is applied.

See Also

formatter

Specifies a custom format.

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

JavaScript
format: function (value) {
    // ...
    return formattedValue;
}
See Also

parser

Parses string values into numeric or date-time values. Can 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 widget 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) {
    var month = date.getMonth() + 1,
        day = date.getDate(),
        year = date.getFullYear();

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

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

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'

View Demo

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'

You can choose one of the predefined formats, depending on the values you need to format, from the following groups:

Numeric Formats

  • "fixedPoint" - 100.11 → 100
  • "percent" - 0.1 → 10%
  • "decimal" - 100.11 → 100
  • "exponential" - 1 000 → 1E+3
  • "thousands" - 1 000.11 → 1K
  • "millions" - 1 000 000.11 → 1M
  • "billions" - 1 000 000 000.11 → 1B
  • "trillions" - 1 000 000 000 000 → 1T
  • "largeNumber"*
* - uses "thousands", "millions", "billions", "trillions"* format depending on the actual value
NOTE
Specify the precision to show fractional numbers.

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"
  • "second" - "00"
  • "minute" - "00"
  • "hour" - "12"
  • "day" - "01"
  • "dayOfWeek" - "Thursday"
  • "month" - "January"
  • "quarter" - "QI"
  • "year" - "1970"

Currency Formats

  • "currency" - "$3.95"*
* - to define any other currency, use 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 the 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"

When using a widget as an ASP.NET MVC Control, 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.

View Demo

See Also