Skip to content
Titanium SDK
Version13.4.1

Global.Intl.NumberFormat

moduleAndroidiPhoneiPadmacOSsince iPhone 6.0.0, iPad 6.0.0, Android 9.1.0, macOS 9.2.0

Immutable object used to convert numbers to localized numeric strings.

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.

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 1

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

Syntax

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

Parameters

  • locales: String/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 Titanium.Locale.currentLocale.

  • options: NumberFormatOptions (optional)

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

Methods 4

Formats the given number to a localized numeric string.

Parameters
ParametersTypeDescription
valueNumber

The number to be formatted.

Returns String

The localized numeric string.

formatToParts

iOS 13.0+

Formats given number to an array of components describing what the formatted 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 characters, currency characters, currency symbol positions, etc.

For more detail, see the MDN website about formatToParts.

Parameters
ParametersTypeDescription
valueNumber

The number to be formatted into parts.

Returns Array<NumberFormattedPart>

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

Gets the object's formatting options.

Returns the formatting options the format object uses.

For more detail, see the MDN website about resolvedOptions.

Returns NumberFormatOptions

Returns the formatting options used.

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

For more detail, see the MDN website about supportedLocalesOf.

Parameters
ParametersTypeDescription
localesString | Array<String>

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

Returns Array<String>

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