numerable
Advanced tools
Readme
numerable is a number formatting library for Javascript and Typescript apps.
Use npm or yarn to install numerable.
npm install --save numerable
# or
yarn add numerable
import { format, parse } from 'numerable';
format(1500250.2, '0,0.00');
//=> '1,500,250.20'
format(0.25, '0.0 %');
//=> '25.0 %'
format(1200, '0.00 a');
//=> '1.20 K'
parse('80.5%');
//=> 0.805
Numbers formatting in numerable is done through a pattern-based syntax. With these patterns you can easily define common number formats, similar to date formatting.
The numeric pattern syntax defines:
Examples
| Number | Pattern | Result | Locale |
|---|---|---|---|
| 10000 | "0,0.0000" | "10,000.0000" | en (English) |
| 1.23 | "0.0" | "1.2" | en (English) |
| 10000.23 | "0,0" | "10,000" | en (English) |
| 1000.2345 | "0,0.X" | "1,000.2345" | en (English) |
| 1000.2345 | "0,0.X" | "1 000,2345" | fr (French) |
| 0 | "0.00" | "0,00" | fr (French) |
| -10000 | "0,0.0" | "-10.000,0" | es (Spanish) |
| 10000.1234 | "0.000" | "10000.123" | en (English) |
| 10000.001 | "0[.]00" | "10000" | en (English) |
| 10000 | "(0,0.0)" | "10,000.0" | en (English) |
| -10000 | "(0,0.0)" | "(10,000.0)" | en (English) |
| -12300 | "+0,0.00" | "-12,300.00" | en (English) |
| 12300 | "+0,0.00" | "+1,2300.00" | ja (Japanese) |
| 1230 | "0,0+" | "1,230+" | en (English) |
| 1230 | "0,0-" | "1,230" | en (English) |
| 0.67 | "0.0####" | "0.67" | en (English) |
| 0.67 | "0.000##" | "0.670" | en (English) |
| 3162.63 | "0.0####" | "3162.63" | en (English) |
| 3162.6338 | "0.0####" | "3162.6338" | en (English) |
| 0.23 | "000.##" | "000.23" | en (English) |
| 1234.567 | "0,0.00" | "١٬٢٣٤٫٥٧" | arEG (Arabic) |
| undefined | "0,0.00" | "" | en (English) |
| null | "0.00" | "" | en (English) |
| NaN | "0.0" | "" | en (English) |
By adding the % symbol to any of the previous patterns, the value is multiplied by 100 and the % symbol is added in the place indicated.
| Number | Pattern | Result | Locale |
|---|---|---|---|
| 0.52 | "0.##%" | "52%" | en (English) |
| 1 | "0.##%" | "100%" | en (English) |
| 1 | "0,0.00 %" | "100.00 %" | en (English) |
| -0.88 | "0 %" | "-88 %" | en (English) |
If an abbreviation is specified in the pattern (a), numerable will look for the shortest abbreviation for your number, and it will display the number with a locale-specific abbreviation.
| Number | Pattern | Result | Locale |
|---|---|---|---|
| 2000000000 | "0.0a" | "2.0B" | en (English) |
| 1230974 | "0.0a" | "1.2M" | en (English) |
| 2460 | "0 a" | "2 mil" | es (Spanish) |
| -104000 | "0 a" | "-104 K" | en (English) |
| 999950 | "0.0a" | "1.0тыс." | ru (Russian) |
| 999999999 | "0 a" | "1 Mio." | de (German) |
numerable will format the currency symbol if the currency ISO code (ISO 4217) is passed as a format option (e.g. format(155, '$ 0.00', { currency: 'EUR' })) and the dollar symbol ($) is found in the pattern.
| Number | Pattern | Result | Currency |
|---|---|---|---|
| 1500.143 | "$0,0.00" | "$1,500.14" | USD (US Dollar) |
| 1500.143 | "$0,0.00" | "€1,500.14" | EUR (Euro) |
| -1500.143 | "0,0.00 $" | "-1,500.14 £" | GBP (Pound Sterling) |
| 1500.143 | "0,0.00 $" | "1,500.14 ¥" | JPY (Yen) |
| 1500.143 | "(0,0.00 $)" | "1,500.14 CN¥" | CNY (Yuan Renminbi) |
| -1500.143 | "(0,0.00 $)" | "(1,500.14 A$)" | AUD (Australian dollar) |
numerable allows you to format bytes by adding the 'bd' or 'bb' characters to the pattern.
| Number | Pattern | Result | Locale |
|---|---|---|---|
| 3500 | "0.00bd" | "3.50KB" | en (English) |
| 3500 | "0.00bb" | "3.42KiB" | en (English) |
| -3500000 | "0.00bb" | "-3.34MiB" | en (English) |
| 2444222000000 | "0.00bd" | "2.44TB" | en (English) |
| 2444222000000 | "0.00bb" | "2.22TiB" | en (English) |
numerable allows you to format ordinal numbers based on the locale. The character 'o' in the mask will enable the ordinal numbers formatting.
| Number | Pattern | Result | Locale |
|---|---|---|---|
| 1 | "0o" | "1st" | en (English) |
| 2 | "0o" | "2nd" | en (English) |
| 3 | "0o" | "3rd" | en (English) |
| 4 | "0o" | "4th" | en (English) |
| 1 | "0o" | "1er" | fr (French) |
| 12 | "0o" | "12º" | es (Spanish) |
| 8 | "0o" | "8." | de (German) |
Given an amount of seconds, it will display hours, minutes, and seconds.
| Number | Pattern | Result | Locale |
|---|---|---|---|
| 0 | "00:00:00" | "0:00:00" | en (English) |
| 37 | "00:00:00" | "0:00:37" | en (English) |
| 520 | "00:00" | "0:08:40" | en (English) |
| 48923 | "00:00" | "13:35:23" | en (English) |
| -48923 | "00:00" | "-13:35:23" | en (English) |
- Syntax
format(number, [pattern="0,0.##########"], [options=DEFAULT_OPTIONS])
number
pattern
"0.00""0,0.00##""0,0.00 %""0.0 a"options
format(1234.56, '0,0.00', {
defaultPattern: '0,0.##########',
nullFormat: 'N/A',
nanFormat: 'NaN',
zeroFormat: '-',
rounding: 'floor',
locale: fr,
});
defaultPattern:
rounding:
nullFormat:
nanFormat:
zeroFormat:
locale:
scalePercentage:
trim:
signedZero:
format(-0.008, '0.0', { signedZero: true }) //=> '-0.0'format(0.008, '+0.0', { signedZero: true }) //=> '+0.0'nonBreakingSpace:
- Syntax
parse(numberString, [options=DEFAULT_OPTIONS])
numberString
options
numerable includes two functions that support i18n:
In order to handle internationalization:
import { format, parse } from 'numerable';
import { es, enIN, fr, de } from 'numerable/locale';
format(2500000, '0,0.0 a', { locale: es }); //=> '2,5 M'
format(2500000, '0,0.0 a', { locale: enIN }); //=> '25.0 L'
format(2500000.25, '0,0.00', { locale: fr }); //=> '2 500 000,25'
format(1.5, '0.00', { locale: de }); //=> '1,5'
parse('1,5', { locale: de }); //=> 1.5
To make your app internationalization handling easy, you can create your own function wrappers and use those instead of the original functions. With this approach, you can make your app localized number formatting API simple.
// my-app/utils/format.js
import { format } from 'numerable';
import { es, fr, enIN } from 'numerable/locale';
const locales = {
es,
fr,
'en-in': enIN,
};
export default function (value, pattern = '0,0.000', options) {
const appLocaleId = window.__myLocaleId__;
return format(value, pattern, { locale: locales[appLocaleId], ...options });
}
// Later...
// Importing my custom localized format wrapper
import format from 'my-app/utils/format';
window.__myLocaleId__ = 'es';
format(1234.56, '0,0.00');
// => "1.234,56"
// With our wrapper function, if the pattern is omitted, it will take the default from the wrapper function.
window.__myLocaleId__ = 'fr';
format(1234.56);
// => "1 234,560"
window.__myLocaleId__ = 'en-in';
format(123456789.12, '0,0.0');
// => "12,34,56,789.1"
// 'en' will work, as it is the default locale of numerable
window.__myLocaleId__ = 'en';
format(1234.56, '0,0.00');
// => "1,234.56"
If a NumerableLocale is provided in any format function, it will format the number with the specified locale.
The locales provided by numerable allow localized support for the following formatting options:
import { format } from 'numerable';
import { fr, es, enIN, zh } from 'numerable/locale';
format(1234.56, '0.000', { locale: fr }); // Returns "1 234,560"
format(2500000, '0,0.0 a', { locale: es }); //=> '2,5 M'
format(2500000, '0,0.0 a', { locale: enIN }); //=> '25.0 L'
format(2500000, '0,0.0', { locale: zh }); //=> '250,0000.0'
format(2544609, '0,0.0', { locale: arEG }); //=> '٢٬٥٤٤٬٦٠٩٫٠'
If you app is simple and you are not supporting legacy browsers or Node. You can create a NumerableLocale based on the platform.
:warning: Take into account that the support for platform locales is limited. And some of the features, like "ordinal numbers formatting" won't be available if you obtain the locale from the platform.
numerable provides the function getLocaleFromPlatform. This function will dynamically generate a NumerableLocale using the platform Intl.NumberFormat configuration.
import { format, getLocaleFromPlatform } from 'numerable';
format(2500, '0,0.0 a', { locale: getLocaleFromPlatform('fr') }); //=> '2,5 k'
format(2500, '0,0.0 a', { locale: getLocaleFromPlatform('cs') }); //=> '2,5 tis.'
format(2500, '0.0 a', { locale: getLocaleFromPlatform('es') }); //=> '2,5 mil'
Cons:
- Some features won't work on legacy browsers like IE11 or Node (they will fallback to en language), resulting in potential inconsistency across browsers.
- No full support for formatting features like "ordinal number formatting"
numerable started as a fork from Adam Draper's project Numeral.js.
It has been completely rewriten in Typescript with a functional API and extended features.
Also, date-fns served as inspiration for some of the features.
The patterns used in numerable are an extended version of the original patterns created by Numeral.js.
Pull requests are welcome. For major changes, please open an issue first to discuss what you would like to change.
Please make sure to update tests as appropriate.
FAQs
Number formatting library for Javascript and Node.js apps
The npm package numerable receives a total of 3,196 weekly downloads. As such, numerable popularity was classified as popular.
We found that numerable demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Tea.xyz, a crypto project aimed at rewarding open source contributions, is once again facing backlash due to an influx of spam packages flooding public package registries.
Security News
As cyber threats become more autonomous, AI-powered defenses are crucial for businesses to stay ahead of attackers who can exploit software vulnerabilities at scale.
Security News
UnitedHealth Group disclosed that the ransomware attack on Change Healthcare compromised protected health information for millions in the U.S., with estimated costs to the company expected to reach $1 billion.