Formatted Number

A lightning:formattedNumber component displays formatted numbers for decimals, currency, and percentages. This component uses the Intl.NumberFormat JavaScript object to format numerical values. The locale set in your Salesforce user settings determines where to display spaces, commas, and periods in numbers, and the currency used by default. See the Usage Considerations section for limitations in some locales.

The component has several attributes that specify how number formatting is handled in your app. Among these attributes are minimumSignificantDigits and maximumSignificantDigits. Significant digits refer to the accuracy of a number. For example, 1000 has one significant digit, but 1000.0 has five significant digits. By default, lightning:formattedNumber displays the value 1000.0 as 1000. To display the decimal and trailing zero, set minimumSignificantDigits to 5.

Customize the number of decimal places displayed using maximumFractionDigits and minimumFractionDigits.

Decimal numbers default to 3 decimal places. This example returns 1234.568.

To display all four decimal places, add the attribute minimumFractionDigits="4". This example returns 1234.5678.

Currency numbers default to 2 decimal places. In this example, the formatted number displays as $5,000.00.

The currencyDisplayAs attribute changes the currency display to use the symbol, code, or name of the currency.

To change the number of decimal places, use one or both of the minimumFractionDigits and maximumFractionDigits attributes.

This example renders ¥4,000, using minimumFractionDigits="0" to prevent display of decimals.

This example renders KWD 500.000, using minimumFractionDigits to ensure three decimal places are displayed.

Specify style="percent" to display the value multiplied by 100 as a percent value. Percentages default to 0 decimal places, with rounding. In this example, the formatted number displays as 50%.

To preserve the decimal points, use the maximumFractionDigits attribute. In this example, the formatted number displays as 50.3%.

To display the value as-is without multiplying it by 100, specify style="percent-fixed". In this example, the formatted number displays as 1% because decimal places are not displayed by default and the value is rounded.

Add the attribute maximumFractionDigits="3" to display the percentage as 0.503%.

Large numbers with more than approximately 15 or 16 total digits can't be formatted correctly. In these cases, the formatted value is displayed with precision loss.

The component renders $123,456,789,012,345,680.00, which is a loss in precision.

To prevent precision loss when working with large numbers, consider using a string instead.

The locale set in your Salesforce user preferences determines how numbers are formatted. Some locales such as the Arabic (Lebanon) and Bangla (Bangladesh) locales also specify a numeral system other than the Hindu-Arabic numerals 0-9. The org permission “Show Hindu-Arabic Numbers” is intended to override a locale's default numerals. However, lightning:formattedNumber displays the locale's default numerals even when this permission is enabled in your org. See Supported Number, Name, and Address Formats (ICU).

To display your numbers correctly when the permission is enabled, use the $A.localizationService.formatNumber() JavaScript API. See AuraLocalizationService.