# Global.Intl.NumberFormat

Immutable object used to convert numbers to localized numeric strings.

Availability
9.1.0
6.0.0
9.2.0
Extends
Object

# Overview

A NumberFormat object is used to convert a Number value to a localized numeric string. It provides various formatting options controlling the number of integer and fractional digits to be displayed. It can also output currency values, percentage based values, and scientific notation.

For more detail, see the MDN website about Intl.NumberFormat (opens new window).

# Examples

# Format with Leading Zeros

// Set up to pad first 3 integer digits with zeros if needed.
const formatter = new Intl.NumberFormat(Ti.Locale.currentLocale, {
    minimumIntegerDigits: 3,
    useGrouping: false
});

// Logs: 000
console.log(formatter.format(0));

// Logs: 001
console.log(formatter.format(1));

// Logs: 001.23
console.log(formatter.format(1.23));

// Logs: 12345
console.log(formatter.format(12345));

# Round to Significant Digits

// Round up to 3 significant digits.
// All trailing non-fractional digits will be zero.
const formatter = new Intl.NumberFormat(Ti.Locale.currentLocale, {
    maximumSignificantDigits: 3,
    useGrouping: false
});

// Logs: 12300
console.log(formatter.format(12345.6));

// Logs: -12300
console.log(formatter.format(-12345.6));

// Logs: 1.23
console.log(formatter.format(1.23456));

# Currency Format

// Set up currency style format options.
const options = {
    style: 'currency',
    maximumFractionDigits: 2,
    minimumFractionDigits: 2,
    useGrouping: true
};

// Format in dollars in USA. Logs: $1,000.00
// Note that the "currency" option is required.
let formatter = Intl.NumberFormat('en-US', Object.assign({ currency: 'USD' }, options));
console.log(formatter.format(1000));

// Format in euros in USA. Logs: €1,000.00
formatter = Intl.NumberFormat('en-US', Object.assign({ currency: 'EUR' }, options));
console.log(formatter.format(1000));

// Format in euros in Germany. Logs: 1.000,00 €
formatter = Intl.NumberFormat('de-DE', Object.assign({ currency: 'EUR' }, options));
console.log(formatter.format(1000));

// Format in dollars in Germany. Logs: 1.000,00 $
formatter = Intl.NumberFormat('de-DE', Object.assign({ currency: 'USD' }, options));
console.log(formatter.format(1000));

# Percentage Format

// Set up percentage style numeric formatting.
const formatter = new Intl.NumberFormat(Ti.Locale.currentLocale, {
    style: 'percent',
    maximumFractionDigits: 1,
    minimumFractionDigits: 1,
    useGrouping: false
});

// Logs: 25.0%
console.log(formatter.format(0.25));

// Logs: 100.0%
console.log(formatter.format(1.0));

// Logs: 1234.5%
console.log(formatter.format(12.345));

// Logs: 1234.6%
// Since value exceeds "maximumFractionDigits" of 1, it is rounded.
console.log(formatter.format(12.3456));

# Scientific Notation (Android Only)

// Logs: 1.235E5
// Decimal point will be a period, comma, or space depending on the locale.
const formatter = new Intl.NumberFormat(Ti.Locale.currentLocale, { notation: 'scientific' });
console.log(formatter.format(123456.7));

# Properties

# constructor READONLY

Availability
9.1.0
6.0.0
9.2.0

Creates a new Intl.NumberFormat object with the given locale and formatting options.

# Syntax

new Intl.NumberFormat([locales[, options]])

# Parameters

  • locales: Global.String/Global.String[] (optional)

    The BCP 47 language and country code(s) to use for localized formatting. Can provide multiple locales where the best-supported locale will be favored in the order provided by the array. If parameter is not assigned, then the system may use the 'en-US' locale by default instead of the system's current locale. It's recommended to set this parameter using currentLocale.

  • options: NumberFormatOptions (optional)

    Provides settings indicating how a number should be formatted to a string.

# Methods

# format

Availability
9.1.0
6.0.0
9.2.0
format(value) String

Formats the given number to a localized numeric string.

Parameters

Name Type Description
value Number

The number to be formatted.

Returns

The localized numeric string.

Type
String

# formatToParts

Availability
9.1.0
6.0.0
9.2.0
formatToParts(value) Array<NumberFormattedPart>

Formats given number to an array of components describing what the formmated string would produce.

Returns an array of objects providing the "type" and "value" of each component the formatted string would produce. Can be used to fetch localized separator chracters, currency characters, currency symbol positions, etc.

For more detail, see the MDN website about formatToParts.

Parameters

Name Type Description
value Number

The number to be formatted into parts.

Returns

Array of objects providing the "type" and "value" of each component in formatted string.

Type
Array<NumberFormattedPart>

# resolvedOptions

Availability
9.1.0
6.0.0
9.2.0
resolvedOptions() NumberFormatOptions

Gets the object's formatting options.

Returns the formatting options the format object uses.

For more detail, see the MDN website about resolvedOptions.

Returns

Returns the formatting options used.


# supportedLocalesOf

Availability
9.1.0
6.0.0
9.2.0
supportedLocalesOf(locales) Array<String>

Static method indicating what locales are supported by NumberFormat from the given locale(s).

For more detail, see the MDN website about supportedLocalesOf.

Parameters

Name Type Description
locales String | Array<String>

A string or array of strings providing BCP 47 locale identifiers to query.

Returns

Array containing a subset of the given locale strings supported by NumberFormat objects.

Type
Array<String>