0
# Duration Formatting
1

2
Single duration formatting provides comprehensive control over how individual moment duration objects are converted to formatted strings.
3

4
## Capabilities
5

6
### Format Method
7

8
The primary method for formatting individual duration objects with flexible argument patterns.
9

10
```javascript { .api }
11
/**
12
 * Format a duration using template, precision, and settings
13
 * @param template - Format template string or function (optional)
14
 * @param precision - Number of decimal places or integer truncation (optional)
15
 * @param settings - Configuration object (optional)
16
 * @returns Formatted duration string
17
 */
18
moment.duration.fn.format([template] [, precision] [, settings]): string;
19
```
20

21
**Usage Examples:**
22

23
```javascript
24
var duration = moment.duration(3661, "seconds");
25

26
// Using template only
27
duration.format("h:mm:ss");
28
// "1:01:01"
29

30
// Using precision only
31
duration.format(2);
32
// "1.02 hours" (default template with 2 decimal places)
33

34
// Using settings only
35
duration.format({ template: "h [hrs] m [min]", trim: "both" });
36
// "1 hr 1 min"
37

38
// Using template and precision
39
duration.format("h [hours]", 1);
40
// "1.0 hours"
41

42
// Using template and settings
43
duration.format("h:mm:ss", { forceLength: true });
44
// "01:01:01"
45

46
// Using precision and settings
47
duration.format(1, { template: "m [minutes]" });
48
// "61.0 minutes"
49

50
// Using all three arguments
51
duration.format("h [hrs] m [min]", 1, { trim: "both" });
52
// "1.0 hr 1.0 min"
53
```
54

55
### Default Template Function
56

57
Automatically generates appropriate templates based on duration magnitude.
58

59
```javascript { .api }
60
/**
61
 * Default template function that generates templates based on duration magnitude
62
 * Executed with 'this' binding to settings object
63
 * @returns Template string appropriate for the duration's magnitude
64
 */
65
function defaultFormatTemplate(): string;
66
```
67

68
The default template function analyzes the duration's largest unit type and returns templates optimized for that magnitude:
69

70
- **Milliseconds**: `"S __"` (e.g., "100 milliseconds")
71
- **Seconds/Minutes**: `"*_MS_"` (e.g., "1:40")
72
- **Hours**: `"_HMS_"` (e.g., "1:01:01")
73
- **Days**: `"d __"` or falls through to weeks format
74
- **Weeks**: `"w __, d __, h __"` with trim: "both"
75
- **Months**: `"M __"` or falls through to years format
76
- **Years**: `"y __, M __, d __"` with trim: "both"
77

78
**Usage Examples:**
79

80
```javascript
81
moment.duration(100, "milliseconds").format();
82
// "100 milliseconds"
83

84
moment.duration(100, "seconds").format();
85
// "1:40"
86

87
moment.duration(100, "days").format();
88
// "3 months, 9 days"
89

90
moment.duration(100, "weeks").format();
91
// "1 year, 10 months, 30 days"
92
```
93

94
### Format Defaults
95

96
Global default settings that can be modified to change plugin behavior.
97

98
```javascript { .api }
99
/**
100
 * Default settings object for duration formatting
101
 * Can be modified to change global defaults
102
 */
103
moment.duration.fn.format.defaults: {
104
  template: defaultFormatTemplate,
105
  precision: 0,
106
  trim: null,
107
  largest: null,
108
  maxValue: null,
109
  minValue: null,
110
  trunc: false,
111
  forceLength: null,
112
  userLocale: null,
113
  usePlural: true,
114
  useLeftUnits: false,
115
  useGrouping: true,
116
  useSignificantDigits: false,
117
  stopTrim: null,
118
  useToLocaleString: true,
119
  groupingSeparator: ",",
120
  decimalSeparator: ".",
121
  grouping: [3]
122
};
123
```
124

125
**Usage Examples:**
126

127
```javascript
128
// Change global defaults
129
moment.duration.fn.format.defaults.precision = 2;
130
moment.duration.fn.format.defaults.trim = "both";
131

132
// All subsequent format calls will use new defaults
133
moment.duration(3661, "seconds").format("h [hours]");
134
// "1.02 hours" (with 2 decimal places due to changed default)
135
```
136

137
## Template Processing
138

139
### Token Recognition
140

141
The format function recognizes moment tokens and replaces them with duration values:
142

143
```javascript
144
// Basic tokens
145
moment.duration(1, "year").format("y");        // "1"
146
moment.duration(1, "month").format("M");       // "1"
147
moment.duration(1, "week").format("w");        // "1"
148
moment.duration(1, "day").format("d");         // "1"
149
moment.duration(1, "hour").format("h");        // "1"
150
moment.duration(1, "minute").format("m");      // "1"
151
moment.duration(1, "second").format("s");      // "1"
152
moment.duration(1, "millisecond").format("S"); // "1"
153

154
// Token length controls padding
155
moment.duration(5, "minutes").format("mm");    // "05"
156
moment.duration(5, "minutes").format("mmm");   // "005"
157
```
158

159
### Custom Template Functions
160

161
Create dynamic templates based on duration values or other conditions:
162

163
```javascript
164
function customTemplate() {
165
    // 'this' is bound to the settings object
166
    // 'this.duration' provides access to the duration being formatted
167
    var duration = this.duration;
168
    
169
    if (duration.asSeconds() >= 86400) {
170
        return "w [weeks], d [days]";
171
    } else if (duration.asSeconds() >= 3600) {
172
        return "h:mm:ss";
173
    } else {
174
        return "m:ss";
175
    }
176
}
177

178
moment.duration(65, 'seconds').format(customTemplate);
179
// "1:05"
180

181
moment.duration(1347840, 'seconds').format(customTemplate);
182
// "2 weeks, 2 days"
183
```
184

185
## Value Processing
186

187
### Precision Control
188

189
Positive precision adds decimal places, negative precision truncates integer places:
190

191
```javascript
192
var duration = moment.duration(3661, "seconds");
193

194
// Positive precision - decimal places
195
duration.format("h [hours]", 0);  // "1 hour"
196
duration.format("h [hours]", 1);  // "1.0 hours"
197
duration.format("h [hours]", 2);  // "1.02 hours"
198

199
// Negative precision - integer truncation
200
moment.duration(1234, "seconds").format("s [seconds]", -1);  // "1230 seconds"
201
moment.duration(1234, "seconds").format("s [seconds]", -2);  // "1200 seconds"
202
```
203

204
### Rounding vs Truncation
205

206
Control whether final values are rounded or truncated:
207

208
```javascript
209
var duration = moment.duration(179, "seconds");
210

211
// Default behavior (rounding)
212
duration.format("m [minutes]");           // "3 minutes"
213

214
// Truncation behavior
215
duration.format("m [minutes]", { trunc: true }); // "2 minutes"
216
```