While working on an interactive data visualization I needed to represent a number as a percent for display purposes. Fortunately, thanks to the widely supported Intl.NumberFormat API, this common use case was easy to accomplish with a few lines of code!
Representing a number as a percent with
Intl.NumberFormat begins with adding
style: 'percent' as an option when calling the formatter factory function. This option is all that’s required to create a basic formatter with sensible defaults:
A single formatter instance of
Intl.NumberFormat can also be reused to format multiple numbers:
Configuring decimal precision
You may be wondering what the output of the
format function is if our numbers aren’t so precise? All of the example numbers we’ve seen so far are formatted as a nice round integer:
100%. What happens, though, when the number we’d want to format has more than 2 decimal places? By default
NumberFormat rounds to the nearest whole number; possibly resulting in unexpected values. Example:
As you saw above,
0.125 was rounded up to
13%, when we may have desired an output of
12.5% instead. This degree of rounding would be inaccurate and unacceptable for many data driven purposes. Fortunately, two configuration values give us precise control over this rounding behavior:
minimumFractionDigitsis used to configure how many digits should always be displayed. If the number being formatted does not have digits at those places, zeroes are rendered instead:
maximumFractionDigitsconfigures the maximum number of decimal places that should be displayed, however zeroes are not filled in if those places are non-zero.
Combining both options together gives us a more predictable and user friendly output. If you desired to always display two decimal places regardless of what the values are, you can set both options to
Note that when we used these options the aforementioned rounding still occured- however we had control over how many digits were significant and would be retained.
Intl.NumberFormat API also supports different locales via the first argument. Setting this parameter to the desired locale allows numbers to be formatted according to a region/language specific style. Using our percent format example from above, we were able to easily percentage format a number for a German locale:
Hopefully this post showed how useful
Intl.NumberFormat API can be for formatting percentages. There’s even more options and features that make this API awesome!