Formatted Number

lightning-formatted-number

Displays formatted numbers for decimals, currency, and percentages.

For Use In

Lightning Experience, Experience Builder Sites, Salesforce Mobile App, Lightning Out (Beta), Standalone Lightning App, Mobile Offline

::::::tabset{tabs='["Example", "Develop", "Specifications"]'}

:::::tab

::component-playground{component="formattedNumber" model="lwc" namespace="lightning"}

:::::

:::::tab

A lightning-formatted-number component shows formatted numbers for decimals, currency, and percentages. Use format-style to specify the number style. This component uses the Intl.NumberFormat JavaScript object to format numerical values.

The locale set in your Salesforce user settings determines where to place 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 to specify how to format numbers. Among these attributes are minimum-significant-digits and maximum-significant-digits. 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-formatted-number shows the value 1000.0 as 1000. To include the decimal and trailing zero, set minimum-significant-digits to 5.

<template>
    <lightning-formatted-number value="1000.0" minimum-significant-digits="5">
    </lightning-formatted-number>
</template>

Customize the number of decimal places by using minimum-fraction-digits and maximum-fraction-digits.

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

<template>
    <lightning-formatted-number value="1234.5678"> </lightning-formatted-number>
</template>

To include all four digits in the decimal place, add the attribute minimum-fraction-digits="4".

<template>
    <lightning-formatted-number value="1234.5678" minimum-fraction-digits="4">
    </lightning-formatted-number>
</template>

Work With Currencies

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

<template>
    <lightning-formatted-number
        value="5000"
        format-style="currency"
        currency-code="USD"
    >
    </lightning-formatted-number>
</template>

The currency-display-as 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 minimum-fraction-digits and maximum-fraction-digits attributes.

This example renders ¥4,000 by using minimum-fraction-digits="0" to suppress decimals.

<template>
    <lightning-formatted-number
        value="4000"
        format-style="currency"
        currency-code="JPY"
        minimum-fraction-digits="0"
    >
    </lightning-formatted-number>
</template>

This example renders KWD 500.000 by using minimum-fraction-digits to include three decimal places.

<template>
    <lightning-formatted-number
        value="500"
        format-style="currency"
        currency-code="KWD"
        minimum-fraction-digits="3"
    >
    </lightning-formatted-number>
</template>

Work With Percentages

Specify format-style="percent" to format the number as a percent value. Percentages default to 0 decimal places, with rounding. In this example, the formatted number is 50%.

<template>
    <lightning-formatted-number value="0.503" format-style="percent">
    </lightning-formatted-number>
</template>

To preserve the decimal points, use the maximum-fraction-digits attribute. In this example, the formatted number is 50.3%.

<template>
    <lightning-formatted-number
        value="0.503"
        format-style="percent"
        maximum-fraction-digits="1"
    >
    </lightning-formatted-number>
</template>

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

<template>
    <lightning-formatted-number value="0.503" format-style="percent-fixed">
    </lightning-formatted-number>
</template>

Add the attribute maximum-fraction-digits="3" to set the percentage as 0.503%.

<template>
    <lightning-formatted-number
        value="0.503"
        format-style="percent-fixed"
        maximum-fraction-digits="3"
    >
    </lightning-formatted-number>
</template>

Work with Large Numbers

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

<p>Balance</p>
<lightning-formatted-number
    format-style="currency"
    currency-code="USD"
    value={balance}
></lightning-formatted-number>

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.

// Don't do this
// Large numbers result in precision loss
balance = 123456789012345678;

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

// Do this instead
// Specify a large number using a string
balance = "123456789012345678";

Usage Considerations

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-formatted-number displays the locale's default numerals even when this permission is enabled in your org. See Supported Number, Name, and Address Formats (ICU).

The format-style attribute is called the style attribute in the Aura version of this component. See Base Components: Aura Vs Lightning Web Components.

LWC Recipes

The LWC Recipes GitHub repository contains code examples for Lightning Web Components that you can test in an org.

For a recipe that uses lightning-formatted-date-time, see the c-misc-shared-javascript component.

See Also

Object Reference for the Salesforce Platform: Field Types

:::::

:::::tab ::component-specification{component="formattedNumber" model="lwc" namespace="lightning"}

:::::

::::::