0
# Number Formatting
1

2
Comprehensive formatting system with built-in plugins for currency, percentages, bytes, exponential notation, ordinals, basis points, and time duration formatting. All format plugins support both formatting numbers to strings and unformatting (parsing) strings back to numbers.
3

4
## Capabilities
5

6
### Format Plugin System
7

8
```javascript { .api }
9
/**
10
 * Register a new format plugin
11
 * @param type - Must be 'format' for format plugins
12
 * @param name - Unique name for the format plugin
13
 * @param definition - Format plugin definition object
14
 * @returns The registered format plugin definition
15
 */
16
numeral.register(type: 'format', name: string, definition: FormatPlugin): FormatPlugin;
17

18
interface FormatPlugin {
19
  regexps: {
20
    format: RegExp;      // Pattern to detect when this format should be used
21
    unformat?: RegExp;   // Pattern to detect when unformatting with this plugin
22
  };
23
  format: (value: number, format: string, roundingFunction: Function) => string;
24
  unformat?: (string: string) => number;
25
}
26
```
27

28
### Currency Formatting
29

30
Format numbers with currency symbols and locale-aware placement. Supports prefix and suffix positioning with proper negative number handling.
31

32
```javascript { .api }
33
// Currency format detection pattern: /(\$)/
34
// Triggered by '$' symbol in format string
35

36
// Format patterns:
37
// '$0,0.00' → "$1,234.56"
38
// '0,0.00$' → "1,234.56$"  
39
// '$ 0,0.00' → "$ 1,234.56"
40
// '($ 0,0.00)' → negative: "($ 1,234.56)"
41
```
42

43
**Usage Examples:**
44

45
```javascript
46
const numeral = require('numeral');
47

48
// Basic currency formatting
49
console.log(numeral(1234.56).format('$0,0.00')); // "$1,234.56"
50
console.log(numeral(1234.56).format('0,0.00$')); // "1,234.56$"
51

52
// Currency with spaces
53
console.log(numeral(1234.56).format('$ 0,0.00')); // "$ 1,234.56"
54

55
// Negative currency with parentheses
56
console.log(numeral(-1234.56).format('($0,0.00)')); // "($1,234.56)"
57

58
// Different currency symbols (when locale is set)
59
numeral.locale('fr'); // Sets currency symbol to '€'
60
console.log(numeral(1234.56).format('$0,0.00')); // "€1 234,56"
61
```
62

63
### Percentage Formatting
64

65
Format numbers as percentages with optional scaling by 100 (configurable globally).
66

67
```javascript { .api }
68
// Percentage format detection pattern: /(%)/
69
// Triggered by '%' symbol in format string
70
// Unformat pattern: /(%)/
71

72
// Format patterns:
73
// '0%' → "95%" (0.95 × 100 with scalePercentBy100: true)
74
// '0.00%' → "95.00%"
75
// '0 %' → "95 %" (with space)
76
// '(0%)' → negative: "(5%)" for -0.05
77
```
78

79
**Usage Examples:**
80

81
```javascript
82
// Basic percentage (scaling enabled by default)
83
console.log(numeral(0.95).format('0%')); // "95%"
84
console.log(numeral(0.9567).format('0.00%')); // "95.67%"
85

86
// Percentage with space
87
console.log(numeral(0.95).format('0 %')); // "95 %"
88

89
// Negative percentages
90
console.log(numeral(-0.05).format('0%')); // "-5%"
91
console.log(numeral(-0.05).format('(0%)')); // "(5%)"
92

93
// Parse percentage strings
94
console.log(numeral('95%').value()); // 0.95
95
console.log(numeral('95.67%').value()); // 0.9567
96

97
// Disable percentage scaling
98
numeral.options.scalePercentBy100 = false;
99
console.log(numeral(95).format('0%')); // "95%"
100
console.log(numeral('95%').value()); // 95
101
```
102

103
### Bytes Formatting
104

105
Format numbers as file sizes with both decimal (1000-based) and binary (1024-based) calculations.
106

107
```javascript { .api }
108
// Bytes format detection pattern: /([0\s]i?b)/
109
// Triggered by 'b' or 'ib' in format string
110
// Supports: B, KB, MB, GB, TB, PB, EB, ZB, YB (decimal)
111
//          B, KiB, MiB, GiB, TiB, PiB, EiB, ZiB, YiB (binary)
112

113
// Format patterns:
114
// '0b' → "1KB" (decimal, base 1000)
115
// '0ib' → "1KiB" (binary, base 1024)  
116
// '0.0b' → "1.2KB"
117
// '0 b' → "1 KB" (with space)
118
```
119

120
**Usage Examples:**
121

122
```javascript
123
// Decimal bytes (base 1000)
124
console.log(numeral(1024).format('0b')); // "1KB"
125
console.log(numeral(1536).format('0.0b')); // "1.5KB"
126
console.log(numeral(1048576).format('0b')); // "1MB"
127

128
// Binary bytes (base 1024)  
129
console.log(numeral(1024).format('0ib')); // "1KiB"
130
console.log(numeral(1536).format('0.0ib')); // "1.5KiB"
131
console.log(numeral(1048576).format('0ib')); // "1MiB"
132

133
// Bytes with space
134
console.log(numeral(1024).format('0 b')); // "1 KB"
135

136
// Large sizes
137
console.log(numeral(1099511627776).format('0.0b')); // "1.1TB"
138

139
// Parse byte strings
140
console.log(numeral('1.5KB').value()); // 1500
141
console.log(numeral('1.5KiB').value()); // 1536
142
```
143

144
### Ordinal Formatting
145

146
Format numbers with ordinal suffixes (1st, 2nd, 3rd, etc.) based on current locale rules.
147

148
```javascript { .api }
149
// Ordinal format detection pattern: /(o)/
150
// Triggered by 'o' in format string
151

152
// Format patterns:
153
// '0o' → "1st", "2nd", "3rd", "4th"
154
// '0 o' → "1 st" (with space)
155
// Locale-specific: French "1er", "2e"
156
```
157

158
**Usage Examples:**
159

160
```javascript
161
// Basic ordinals (English)
162
console.log(numeral(1).format('0o')); // "1st"
163
console.log(numeral(2).format('0o')); // "2nd"  
164
console.log(numeral(3).format('0o')); // "3rd"
165
console.log(numeral(4).format('0o')); // "4th"
166
console.log(numeral(21).format('0o')); // "21st"
167
console.log(numeral(22).format('0o')); // "22nd"
168

169
// Ordinals with space
170
console.log(numeral(1).format('0 o')); // "1 st"
171

172
// Different locales
173
numeral.locale('fr');
174
console.log(numeral(1).format('0o')); // "1er"
175
console.log(numeral(2).format('0o')); // "2e"
176
```
177

178
### Exponential/Scientific Notation
179

180
Format numbers in exponential (scientific) notation with customizable precision.
181

182
```javascript { .api }
183
// Exponential format detection pattern: /(e\+|e-)/
184
// Triggered by 'e+' or 'e-' in format string
185
// Unformat pattern: /(e\+|e-)/
186

187
// Format patterns:
188
// '0e+0' → "1e+3" (for 1000)
189
// '0.00e+0' → "1.23e+3" (for 1230)
190
// '0e-0' → "1e-3" (for 0.001)
191
```
192

193
**Usage Examples:**
194

195
```javascript
196
// Basic exponential
197
console.log(numeral(1000).format('0e+0')); // "1e+3"
198
console.log(numeral(0.001).format('0e+0')); // "1e-3"
199

200
// Exponential with decimals
201
console.log(numeral(1234).format('0.00e+0')); // "1.23e+3"
202
console.log(numeral(0.001234).format('0.00e+0')); // "1.23e-3"
203

204
// Large numbers
205
console.log(numeral(1234567).format('0.0e+0')); // "1.2e+6"
206

207
// Parse exponential strings
208
console.log(numeral('1.23e+3').value()); // 1230
209
console.log(numeral('1.23e-3').value()); // 0.00123
210
```
211

212
### Basis Points (BPS) Formatting
213

214
Format numbers as basis points (1/100th of a percent). Commonly used in finance.
215

216
```javascript { .api }
217
// BPS format detection pattern: /(BPS)/
218
// Triggered by 'BPS' in format string  
219
// Unformat pattern: /(BPS)/
220
// Conversion: value × 10000 for display
221

222
// Format patterns:
223
// '0BPS' → "9500BPS" (for 0.95)
224
// '0.0BPS' → "9500.0BPS"
225
// '0 BPS' → "9500 BPS" (with space)
226
```
227

228
**Usage Examples:**
229

230
```javascript
231
// Basic BPS formatting (multiply by 10000)
232
console.log(numeral(0.95).format('0BPS')); // "9500BPS"
233
console.log(numeral(0.0025).format('0BPS')); // "25BPS"
234

235
// BPS with decimals
236
console.log(numeral(0.9567).format('0.0BPS')); // "9567.0BPS"
237

238
// BPS with space
239
console.log(numeral(0.95).format('0 BPS')); // "9500 BPS"
240

241
// Negative BPS
242
console.log(numeral(-0.0025).format('0BPS')); // "-25BPS"
243

244
// Parse BPS strings (divide by 10000)
245
console.log(numeral('9500BPS').value()); // 0.95
246
console.log(numeral('25BPS').value()); // 0.0025
247
```
248

249
### Time Duration Formatting
250

251
Format numbers as time duration in HH:MM:SS format. Input is total seconds.
252

253
```javascript { .api }
254
// Time format detection pattern: /(:)/
255
// Triggered by ':' in format string
256
// Unformat pattern: /(:)/
257
// Input: total seconds, Output: HH:MM:SS or MM:SS
258

259
// Format patterns:
260
// '00:00:00' → "01:23:45" (for 5025 seconds)
261
// '0:0:0' → "1:23:45" (no leading zeros)
262
```
263

264
**Usage Examples:**
265

266
```javascript
267
// Basic time formatting (input in seconds)
268
console.log(numeral(3661).format('00:00:00')); // "01:01:01" (1hr 1min 1sec)
269
console.log(numeral(5025).format('00:00:00')); // "01:23:45" (1hr 23min 45sec)
270

271
// Time without leading zeros
272
console.log(numeral(125).format('0:0:0')); // "2:5" (2min 5sec)
273

274
// Short durations
275
console.log(numeral(65).format('00:00:00')); // "00:01:05" (1min 5sec)
276
console.log(numeral(30).format('00:00:00')); // "00:00:30" (30sec)
277

278
// Parse time strings to seconds
279
console.log(numeral('01:23:45').value()); // 5025
280
console.log(numeral('02:05').value()); // 125 (2min 5sec)
281
console.log(numeral('1:23:45').value()); // 5025
282
```
283

284
## Advanced Formatting Features
285

286
### Abbreviations
287

288
Built-in support for number abbreviations that work with the current locale.
289

290
```javascript { .api }
291
// Abbreviation patterns (work with any base format):
292
// '0a' → "1k", "1m", "1b", "1t" (thousand, million, billion, trillion)
293
// '0.0a' → "1.2k", "1.5m"  
294
// '0 a' → "1 k" (with space)
295
// Force specific: '0ak' (force thousands), '0am' (force millions)
296
```
297

298
**Usage Examples:**
299

300
```javascript
301
// Auto abbreviations
302
console.log(numeral(1000).format('0a')); // "1k"
303
console.log(numeral(1200).format('0.0a')); // "1.2k"
304
console.log(numeral(1000000).format('0a')); // "1m"
305
console.log(numeral(1234567).format('0.0a')); // "1.2m"
306

307
// Forced abbreviations
308
console.log(numeral(1000000).format('0ak')); // "1000k" (force thousands)
309
console.log(numeral(1000).format('0am')); // "0m" (force millions)
310

311
// Currency with abbreviations
312
console.log(numeral(1234567).format('$0.0a')); // "$1.2m"
313
```
314

315
### Negative Number Handling
316

317
Multiple ways to handle negative numbers in formatting.
318

319
```javascript { .api }
320
// Negative number patterns:
321
// Standard: '-0,0' → "-1,234"
322
// Parentheses: '(0,0)' → "(1,234)" for negatives
323
// Signed: '+0,0' → "+1,234" or "-1,234"
324
```
325

326
**Usage Examples:**
327

328
```javascript
329
// Standard negative
330
console.log(numeral(-1234).format('0,0')); // "-1,234"
331

332
// Parentheses for negatives
333
console.log(numeral(-1234).format('(0,0)')); // "(1,234)"
334
console.log(numeral(1234).format('(0,0)')); // "1,234"
335

336
// Always show sign
337
console.log(numeral(1234).format('+0,0')); // "+1,234"
338
console.log(numeral(-1234).format('+0,0')); // "-1,234"
339
```
340

341
### Optional Decimals
342

343
Show decimals only when needed.
344

345
```javascript { .api }
346
// Optional decimal patterns:
347
// '0[.]0' → "1" for 1.0, "1.5" for 1.5
348
// '0[.]00' → "1" for 1.0, "1.50" for 1.5
349
```
350

351
**Usage Examples:**
352

353
```javascript
354
// Optional single decimal
355
console.log(numeral(1.0).format('0[.]0')); // "1"
356
console.log(numeral(1.5).format('0[.]0')); // "1.5"
357

358
// Optional double decimals
359
console.log(numeral(1.0).format('0[.]00')); // "1"
360
console.log(numeral(1.5).format('0[.]00')); // "1.50"
361
console.log(numeral(1.56).format('0[.]00')); // "1.56"
362
```
363

364
## Format String Reference
365

366
### Basic Patterns
367

368
- `0` - Required digit (shows 0 if no digit)
369
- `#` - Optional digit (omitted if zero)
370
- `.` - Decimal separator
371
- `,` - Thousands separator
372
- `[.]` - Optional decimal point
373

374
### Special Symbols
375

376
- `$` - Currency (uses locale currency symbol)
377
- `%` - Percentage (multiplies by 100 if scalePercentBy100 is true)
378
- `a` - Abbreviations (k, m, b, t)
379
- `o` - Ordinal suffixes (st, nd, rd, th)
380
- `e+0` / `e-0` - Exponential notation
381
- `:` - Time format (HH:MM:SS)
382
- `BPS` - Basis points (multiplies by 10000)
383
- `b` - Bytes (decimal base 1000)
384
- `ib` - Bytes (binary base 1024)
385

386
### Sign Handling
387

388
- `()` - Parentheses for negative numbers
389
- `+` - Always show sign (+ or -)
390
- `-` - Show sign only for negative numbers (default)
391

392
### Spacing
393

394
- Add spaces around symbols: `$ 0,0.00`, `0 %`, `0 BPS`