0
# Configuration Settings
1

2
Comprehensive settings system providing fine-grained control over formatting behavior, including trimming, precision, localization, value ranges, and output formatting.
3

4
## Capabilities
5

6
### Settings Object Interface
7

8
Complete configuration interface for customizing duration formatting behavior.
9

10
```javascript { .api }
11
/**
12
 * Settings object for duration formatting
13
 * All properties are optional with intelligent defaults
14
 */
15
interface FormatSettings {
16
  // Core formatting
17
  template?: string | function;
18
  precision?: number;
19
  
20
  // Trimming control
21
  trim?: string | boolean | null;
22
  stopTrim?: string | string[] | null;
23
  largest?: number | null;
24
  
25
  // Value processing
26
  trunc?: boolean;
27
  forceLength?: boolean | null;
28
  useSignificantDigits?: boolean;
29
  
30
  // Value range limits
31
  minValue?: number | null;
32
  maxValue?: number | null;
33
  
34
  // Localization
35
  userLocale?: string | null;
36
  usePlural?: boolean;
37
  useLeftUnits?: boolean;
38
  useToLocaleString?: boolean;
39
  useGrouping?: boolean;
40
  
41
  // Fallback number formatting
42
  groupingSeparator?: string;
43
  decimalSeparator?: string;
44
  grouping?: number[];
45
}
46
```
47

48
## Core Formatting Settings
49

50
### Template
51

52
Controls the format pattern used for output generation.
53

54
```javascript { .api }
55
template?: string | function;
56
// Default: defaultFormatTemplate function
57
```
58

59
**Usage Examples:**
60

61
```javascript
62
// String templates
63
moment.duration(3661, "seconds").format({ template: "h:mm:ss" });
64
// "1:01:01"
65

66
// Function templates
67
function customTemplate() {
68
    return this.duration.asSeconds() > 3600 ? "h [hours]" : "m [minutes]";
69
}
70

71
moment.duration(3661, "seconds").format({ template: customTemplate });
72
// "1 hour"
73
```
74

75
### Precision
76

77
Controls decimal places (positive) or integer truncation (negative).
78

79
```javascript { .api }
80
precision?: number;
81
// Default: 0
82
```
83

84
**Usage Examples:**
85

86
```javascript
87
var duration = moment.duration(3661, "seconds");
88

89
// Positive precision: decimal places
90
duration.format({ template: "h [hours]", precision: 0 });  // "1 hour"
91
duration.format({ template: "h [hours]", precision: 1 });  // "1.0 hours"  
92
duration.format({ template: "h [hours]", precision: 2 });  // "1.02 hours"
93

94
// Negative precision: integer truncation
95
moment.duration(1234, "seconds").format({ 
96
    template: "s [seconds]", 
97
    precision: -1 
98
});  // "1230 seconds"
99

100
moment.duration(1234, "seconds").format({ 
101
    template: "s [seconds]", 
102
    precision: -2 
103
});  // "1200 seconds"
104
```
105

106
## Trimming Control Settings
107

108
### Trim
109

110
Controls which zero-value tokens are removed from output.
111

112
```javascript { .api }
113
trim?: string | boolean | null;
114
// Default: null (treated as "large")
115
// Values: "large", "small", "both", "mid", "final", "all", 
116
//         "left", "right", true, false, null
117
```
118

119
**Usage Examples:**
120

121
```javascript
122
var duration = moment.duration(123, "minutes");
123

124
// "large" - trim largest-magnitude zeros (default)
125
duration.format({ template: "d[d] h:mm:ss", trim: "large" });
126
// "2:03:00"
127

128
// "small" - trim smallest-magnitude zeros  
129
duration.format({ template: "d[d] h:mm:ss", trim: "small" });
130
// "0d 2:03"
131

132
// "both" - trim both ends
133
duration.format({ template: "d[d] h[h] m[m] s[s]", trim: "both" });
134
// "2h 3m"
135

136
// "mid" - trim middle zeros
137
moment.duration(1441, "minutes").format({ 
138
    template: "w[w] d[d] h[h] m[m] s[s]", 
139
    trim: "mid" 
140
});
141
// "0w 1d 1m 0s"
142

143
// "final" - trim final zero
144
moment.duration(0, "minutes").format({ 
145
    template: "d[d] h:mm:ss", 
146
    trim: "large final" 
147
});
148
// ""
149

150
// "all" - shorthand for "both mid final"
151
moment.duration(0, "minutes").format({ 
152
    template: "d[d] h[h] m[m] s[s]", 
153
    trim: "all" 
154
});
155
// ""
156

157
// false - no trimming
158
duration.format({ template: "d[d] h:mm:ss", trim: false });
159
// "0d 2:03:00"
160
```
161

162
### Stop Trim
163

164
Specifies tokens where trimming should stop.
165

166
```javascript { .api }
167
stopTrim?: string | string[] | null;
168
// Default: null
169
// Accepts moment token strings individually or in arrays
170
```
171

172
**Usage Examples:**
173

174
```javascript
175
var duration = moment.duration(23, "minutes");
176

177
// Single token
178
duration.format({ 
179
    template: "d[d] h:mm:ss", 
180
    stopTrim: "h" 
181
});
182
// "0:23:00"
183

184
// Multiple tokens as string
185
moment.duration(2, "hours").format({ 
186
    template: "y [years], d [days], h [hours], m [minutes], s [seconds]",
187
    trim: "both",
188
    stopTrim: "d m"
189
});
190
// "0 days, 2 hours, 0 minutes"
191

192
// Multiple tokens as array
193
moment.duration(2, "hours").format({ 
194
    template: "y [years], d [days], h [hours], m [minutes], s [seconds]",
195
    trim: "both", 
196
    stopTrim: ["d", "m"]
197
});
198
// "0 days, 2 hours, 0 minutes"
199
```
200

201
### Largest
202

203
Limits output to N largest-magnitude tokens with values.
204

205
```javascript { .api }
206
largest?: number | null;
207
// Default: null
208
// Automatically sets trim to "all" when specified
209
```
210

211
**Usage Examples:**
212

213
```javascript
214
var duration = moment.duration(7322, "seconds"); // 2h 2m 2s
215

216
// Show only 2 largest units
217
duration.format({ 
218
    template: "d [days], h [hours], m [minutes], s [seconds]",
219
    largest: 2
220
});
221
// "2 hours, 2 minutes"
222

223
// Interaction with trim setting
224
duration.format({ 
225
    template: "d [days], h [hours], m [minutes], s [seconds]",
226
    largest: 3,
227
    trim: "both"
228
});
229
// "0 days, 2 hours, 2 minutes"
230

231
// Interaction with stopTrim
232
moment.duration(1216800, "seconds").format({
233
    template: "y [years], w [weeks], d [days], h [hours], m [minutes], s [seconds]",
234
    largest: 3,
235
    trim: "both",
236
    stopTrim: "m"
237
});
238
// "2 weeks, 0 days, 2 hours"
239
```
240

241
## Value Processing Settings
242

243
### Trunc
244

245
Controls whether final token values are truncated or rounded.
246

247
```javascript { .api }
248
trunc?: boolean;
249
// Default: false (rounding behavior)
250
```
251

252
**Usage Examples:**
253

254
```javascript
255
var duration = moment.duration(179, "seconds");
256

257
// Default rounding behavior
258
duration.format({ template: "m [minutes]" });           
259
// "3 minutes"
260

261
// Truncation behavior  
262
duration.format({ template: "m [minutes]", trunc: true }); 
263
// "2 minutes"
264

265
// With precision
266
moment.duration(3780, "seconds").format({ 
267
    template: "h [hours]", 
268
    precision: 1,
269
    trunc: false 
270
});
271
// "1.1 hours"
272

273
moment.duration(3780, "seconds").format({ 
274
    template: "h [hours]", 
275
    precision: 1,
276
    trunc: true 
277
});
278
// "1.0 hours"
279
```
280

281
### Force Length
282

283
Forces first token with value to render at full length.
284

285
```javascript { .api }
286
forceLength?: boolean | null;
287
// Default: null (auto-determined by template)
288
```
289

290
**Usage Examples:**
291

292
```javascript
293
var duration = moment.duration(123, "seconds");
294

295
// Default behavior - first token length may be trimmed
296
duration.format({ template: "h:mm:ss" });
297
// "2:03"
298

299
// Force length - first token always full length
300
duration.format({ template: "h:mm:ss", forceLength: true });
301
// "02:03"
302

303
// Compare with explicit token length
304
duration.format({ template: "hh:mm:ss" });
305
// "02:03" (same result, different approach)
306
```
307

308
### Use Significant Digits
309

310
Treats precision as significant digits across all units.
311

312
```javascript { .api }
313
useSignificantDigits?: boolean;
314
// Default: false
315
// Automatically sets trim to "all" when true
316
```
317

318
**Usage Examples:**
319

320
```javascript
321
var duration = moment.duration(99999, "seconds");
322

323
// Regular precision (decimal places on final token)
324
duration.format({ 
325
    template: "d [days], h [hours], m [minutes], s [seconds]",
326
    precision: 3
327
});
328
// "1 day, 3 hours, 46 minutes, 39.000 seconds"
329

330
// Significant digits (across all tokens)
331
duration.format({ 
332
    template: "d [days], h [hours], m [minutes], s [seconds]",
333
    useSignificantDigits: true,
334
    precision: 3
335
});
336
// "1 day, 3 hours, 50 minutes"
337

338
// With truncation
339
duration.format({ 
340
    template: "d [days], h [hours], m [minutes], s [seconds]",
341
    useSignificantDigits: true,
342
    precision: 5,
343
    trunc: true
344
});
345
// "1 day, 3 hours, 46 minutes, 30 seconds"
346
```
347

348
## Value Range Settings
349

350
### Min Value
351

352
Shows "< N units" for small values on least-magnitude token.
353

354
```javascript { .api }
355
minValue?: number | null;
356
// Default: null
357
```
358

359
**Usage Examples:**
360

361
```javascript
362
// Basic min value
363
moment.duration(59, "seconds").format({ 
364
    template: "h [hours], m [minutes]",
365
    minValue: 1
366
});
367
// "< 1 minute"
368

369
// With bubbling to larger units
370
moment.duration(59, "seconds").format({ 
371
    template: "m:ss",
372
    minValue: 60
373
});
374
// "< 1:00"
375

376
// With negative durations
377
moment.duration(-59, "seconds").format({ 
378
    template: "h [hours], m [minutes]",
379
    minValue: 1
380
});
381
// "> -1 minute"
382

383
// With decimal min values
384
moment.duration(89, "seconds").format({ 
385
    template: "m",
386
    minValue: 1.5,
387
    precision: 1
388
});
389
// "< 1.5"
390
```
391

392
### Max Value
393

394
Shows "> N units" for large values on greatest-magnitude token.
395

396
```javascript { .api }
397
maxValue?: number | null;
398
// Default: null
399
// Automatically sets trim to "all" when specified
400
```
401

402
**Usage Examples:**
403

404
```javascript
405
// Basic max value
406
moment.duration(15, "days").format({ 
407
    template: "w [weeks]",
408
    maxValue: 2
409
});
410
// "> 2 weeks"
411

412
// With negative durations
413
moment.duration(-15, "days").format({ 
414
    template: "w [weeks]",
415
    maxValue: 2
416
});
417
// "< -2 weeks"
418

419
// With multiple tokens (lesser tokens forced to 0)
420
moment.duration(15.5, "days").format({ 
421
    template: "w [weeks], d [days], h [hours]",
422
    maxValue: 2,
423
    trim: false,
424
    largest: 2
425
});
426
// "> 2 weeks, 0 days"
427
```
428

429
## Localization Settings
430

431
### User Locale
432

433
Specifies locale for numerical formatting (overrides moment locale).
434

435
```javascript { .api }
436
userLocale?: string | null;
437
// Default: null (uses moment.locale())
438
```
439

440
**Usage Examples:**
441

442
```javascript
443
var duration = moment.duration(1234567, "seconds");
444

445
// Default locale formatting
446
duration.format({ template: "m [minutes]", precision: 3 });
447
// "20,576.117 minutes"
448

449
// German locale formatting
450
duration.format({ 
451
    template: "m [minutes]", 
452
    precision: 3,
453
    userLocale: "de-DE" 
454
});
455
// "20.576,117 minutes"
456
```
457

458
### Use Plural
459

460
Enables automatic pluralization of unit labels.
461

462
```javascript { .api }
463
usePlural?: boolean;
464
// Default: true
465
```
466

467
**Usage Examples:**
468

469
```javascript
470
// With pluralization (default)
471
moment.duration(1, "minutes").format("m [minutes]");
472
// "1 minute"
473
moment.duration(2, "minutes").format("m [minute]");  
474
// "2 minutes"
475

476
// Without pluralization
477
moment.duration(1, "minutes").format({ 
478
    template: "m [minutes]",
479
    usePlural: false 
480
});
481
// "1 minutes"
482
moment.duration(2, "minutes").format({ 
483
    template: "m [minute]",
484
    usePlural: false 
485
});
486
// "2 minute"
487
```
488

489
### Use Left Units
490

491
Processes units to the left of tokens instead of right.
492

493
```javascript { .api }
494
useLeftUnits?: boolean;
495
// Default: false
496
```
497

498
**Usage Examples:**
499

500
```javascript
501
var duration = moment.duration(7322, "seconds");
502

503
// Default behavior (units on right)
504
duration.format("h [hours], m [minutes], s [seconds]");
505
// "2 hours, 2 minutes, 2 seconds"
506

507
// Left units behavior
508
duration.format({ 
509
    template: "[hours] h, [minutes] m, [seconds] s",
510
    useLeftUnits: true 
511
});
512
// "hours 2, minutes 2, seconds 2"
513

514
// With auto-localization
515
duration.format({ 
516
    template: "_ h, _ m, _ s",
517
    useLeftUnits: true 
518
});
519
// "hrs 2, mins 2, secs 2"
520
```
521

522
### Use Grouping
523

524
Enables digit grouping in numerical output.
525

526
```javascript { .api }
527
useGrouping?: boolean;  
528
// Default: true
529
```
530

531
**Usage Examples:**
532

533
```javascript
534
var duration = moment.duration(1234, "seconds");
535

536
// With grouping (default)
537
duration.format("s [seconds]");
538
// "1,234 seconds"
539

540
// Without grouping
541
duration.format({ 
542
    template: "s [seconds]",
543
    useGrouping: false 
544
});
545
// "1234 seconds"
546
```
547

548
## Fallback Number Formatting Settings
549

550
Used when native `toLocaleString` or `Intl.NumberFormat` are unavailable or disabled.
551

552
### Use To Locale String
553

554
Controls whether to use native number formatting APIs.
555

556
```javascript { .api }
557
useToLocaleString?: boolean;
558
// Default: true
559
```
560

561
### Grouping Separator
562

563
Thousands separator for fallback formatting.
564

565
```javascript { .api }
566
groupingSeparator?: string;
567
// Default: ","
568
```
569

570
### Decimal Separator
571

572
Decimal point character for fallback formatting.
573

574
```javascript { .api }
575
decimalSeparator?: string;
576
// Default: "."
577
```
578

579
### Grouping Pattern
580

581
Digit grouping pattern for fallback formatting.
582

583
```javascript { .api }
584
grouping?: number[];
585
// Default: [3] (standard thousands grouping)
586
```
587

588
**Usage Examples:**
589

590
```javascript
591
// Custom fallback number formatting
592
moment.duration(100000.1, "seconds").format({ 
593
    template: "s",
594
    userLocale: "de-DE",
595
    precision: 2,
596
    useToLocaleString: false,    // Force fallback
597
    decimalSeparator: ",",
598
    groupingSeparator: ".",
599
    grouping: [3]
600
});
601
// "100.000,10"
602

603
// Indian locale-style grouping
604
moment.duration(100000000000, "seconds").format({ 
605
    template: "m",
606
    useToLocaleString: false,
607
    precision: 2,
608
    decimalSeparator: ",",
609
    groupingSeparator: " ",
610
    grouping: [3, 2]  // Thousand/lakh/crore grouping
611
});
612
// "1 66 66 66 666,67"
613
```