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.

1<aura:component>
2
3  <lightning:formattedNumber value="1000.0" minimumSignificantDigits="5" />
4
5</aura:component>

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

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

1<aura:component>
2
3  <lightning:formattedNumber value="1234.5678" />
4
5</aura:component>

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

1<aura:component>
2
3  <lightning:formattedNumber value="1234.5678" minimumFractionDigits="4" />
4
5</aura:component>

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

1<aura:component>
2
3  <lightning:formattedNumber value="5000" style="currency" currencyCode="USD" />
4
5</aura:component>

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.

1<aura:component>
2
3  <lightning:formattedNumber
4    value="4000"
5    style="currency"
6    currencyCode="JPY"
7    minimumFractionDigits="0"
8  />
9
10</aura:component>

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

1<aura:component>
2
3  <lightning:formattedNumber
4    value="500"
5    style="currency"
6    currencyCode="KWD"
7    minimumFractionDigits="3"
8  />
9
10</aura:component>

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%.

1<aura:component>
2
3  <lightning:formattedNumber value="0.503" style="percent" />
4
5</aura:component>

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

1<aura:component>
2
3  <lightning:formattedNumber value="0.503" style="percent" maximumFractionDigits="1" />
4
5</aura:component>

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.

1<aura:component>
2
3  <lightning:formattedNumber value="0.503" style="percent-fixed" />
4
5</aura:component>

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

1<aura:component>
2
3  <lightning:formattedNumber value="0.503" style="percent-fixed" maximumFractionDigits="3" />
4
5</aura:component>

To prevent precision loss when working with large numbers with more than 15 or 16 digits, specify the numbers as a string.

1<aura:component>
2
3  <aura:attribute name="balance" type="Decimal" />
4
5  <aura:handler name="init" value="{!this}" action="{!c.doInit}" />
6
7  <lightning:formattedNumber value="{!v.balance}" style="currency" currencyCode="USD" />
8
9</aura:component>

When you specify the number in JavaScript without using a string, the component renders $123,456,789,012,345,680.00, which is a loss in precision.

1// Don't do this
2// Large numbers result in precision loss
3({
4  doInit: function (cmp) {
5    var num = 123456789012345678;
6    cmp.set("v.balance", num);
7  },
8});

To prevent precision loss for large numbers, use a string instead.

1// Do this instead
2// Specify a large number using a string
3({
4  doInit: function (cmp) {
5    var str = "123456789012345678";
6    cmp.set("v.balance", str);
7  },
8});

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.