Formatting Numbers
Formatting is the core feature of Numeral.js. The .format() method provides a powerful way to convert numbers into human-readable strings.
numeral(1234.56).format('0,0.00'); // '1,234.56'The .format() method accepts an optional rounding function as its second argument. The default is Math.round.
numeral(10.55).format('0'); // '11'
numeral(10.45).format('0', Math.floor); // '10'Format Specifiers
Here is a comprehensive list of all the available format specifiers.
Numbers
| Format String | Example Input | Output |
|---|---|---|
'0,0' |
10000 |
'10,000' |
'+0,0' |
1230 |
'+1,230' |
'-0,0' |
-1230 |
'-1,230' |
'0.000' |
10000.1234 |
'10000.123' |
'0[.]00' |
10000 |
'10000' |
'0[.]00' |
10000.123 |
'10000.12' |
'(0,0)' |
-10000 |
'(10,000)' |
'00000' |
10 |
'00010' |
Abbreviations
Use 'a' to abbreviate large numbers. You can also force a specific abbreviation (ak, am, ab, at).
| Format String | Example Input | Output |
|---|---|---|
'0a' |
1460 |
'1k' |
'0.0a' |
1230974 |
'1.2m' |
'0 a' |
-104000 |
'-104 k' |
'0,0 at' |
5444333222111 |
'5 t' |
Currency
The $ symbol acts as a placeholder for the currency symbol defined in the current locale (e.g., $, €, £).
| Format String | Example Input | Output (en locale) |
|---|---|---|
'$0,0.00' |
1000.234 |
'$1,000.23' |
'$ 0,0' |
1001 |
'$ 1,001' |
'(0,0$)' |
-1000 |
'(1,000$)' |
'$ (0.00a)' |
1230974 |
'$ 1.23m' |
Bytes
Format file sizes using decimal (b) or binary (ib) standards.
| Format String | Example Input | Output |
|---|---|---|
'0b' |
1000 |
'1KB' |
'0 ib' |
1024 |
'1 KiB' |
'0.00b' |
2500 |
'2.50KB' |
'0.0 ib' |
5368709120 |
'5.0 GiB' |
Percentages
By default, Numeral.js scales numbers by 100 when formatting as a percentage. This can be disabled in the global options.
| Format String | Example Input | Output |
|---|---|---|
'0%' |
1 |
'100%' |
'0.000%' |
0.97487 |
'97.487%' |
'(0 %)' |
-0.43 |
'(43 %)' |
Time
Format a number of seconds into a time string.
| Format String | Example Input | Output |
|---|---|---|
'00:00:00' |
25 |
'0:00:25' |
'00:00:00' |
238 |
'0:03:58' |
'00:00:00' |
63846 |
'17:44:06' |
Ordinals
Adds the ordinal suffix based on the current locale's rules.
| Format String | Example Input | Output (en locale) |
|---|---|---|
'0o' |
1 |
'1st' |
'0o' |
52 |
'52nd' |
'0o' |
23 |
'23rd' |
'0,0o' |
1234 |
'1,234th' |
Exponential
| Format String | Example Input | Output |
|---|---|---|
'0e+0' |
77.1234 |
'8e+1' |
'0.0e+0' |
77.1234 |
'7.7e+1' |
'0.00e-0' |
-0.000000771 |
'-7.71e-7' |
Basis Points (BPS)
| Format String | Example Input | Output |
|---|---|---|
'0 BPS' |
0.0001 |
'1 BPS' |
'0 BPS' |
0.0056 |
'56 BPS' |
'0BPS' |
0.25 |
'2500BPS' |