0
# Display and Formatting
1

2
Comprehensive formatting system with customizable format strings, relative time display, calendar formatting, and localized output for displaying Moment instances in various human-readable formats.
3

4
## Capabilities
5

6
### Basic Formatting
7

8
Core formatting methods for converting Moment instances to strings with customizable format patterns.
9

10
```javascript { .api }
11
/**
12
 * Format the moment according to the given format string
13
 * @param format - Format string using tokens (defaults to ISO 8601)
14
 * @returns Formatted date string
15
 */
16
format(format?: string): string;
17

18
/**
19
 * Get string representation (same as format() with no arguments)
20
 * @returns ISO 8601 formatted string
21
 */
22
toString(): string;
23

24
/**
25
 * Get ISO 8601 string representation
26
 * @param keepOffset - Whether to keep the current UTC offset (default: false)
27
 * @returns ISO 8601 formatted string
28
 */
29
toISOString(keepOffset?: boolean): string;
30

31
/**
32
 * Get JSON representation (same as toISOString())
33
 * @returns ISO 8601 formatted string for JSON serialization
34
 */
35
toJSON(): string;
36

37
/**
38
 * Get debug representation for console.log and debugging
39
 * @returns String representation for debugging
40
 */
41
inspect(): string;
42
```
43

44
**Usage Examples:**
45

46
```javascript
47
import moment from "moment";
48

49
const date = moment("2023-12-25T15:30:45.123Z");
50

51
// Basic formatting
52
console.log(date.format()); // "2023-12-25T15:30:45Z" (default ISO 8601)
53
console.log(date.toString()); // Same as format()
54

55
// Custom formats
56
console.log(date.format("YYYY-MM-DD")); // "2023-12-25"
57
console.log(date.format("MMMM Do, YYYY")); // "December 25th, 2023"
58
console.log(date.format("dddd, MMMM DD, YYYY h:mm A")); // "Monday, December 25, 2023 3:30 PM"
59
console.log(date.format("DD/MM/YYYY HH:mm:ss")); // "25/12/2023 15:30:45"
60

61
// ISO string formatting
62
console.log(date.toISOString()); // "2023-12-25T15:30:45.123Z"
63
console.log(date.toISOString(true)); // Keeps offset if not UTC
64

65
// JSON serialization
66
console.log(JSON.stringify({ date })); // {"date":"2023-12-25T15:30:45.123Z"}
67
```
68

69
### Relative Time Formatting
70

71
Methods for displaying time relative to other moments or the current time.
72

73
```javascript { .api }
74
/**
75
 * Get relative time from now
76
 * @param withoutSuffix - Remove "ago" or "in" suffix (default: false)
77
 * @returns Relative time string like "2 hours ago" or "in 3 days"
78
 */
79
fromNow(withoutSuffix?: boolean): string;
80

81
/**
82
 * Get relative time to now (opposite of fromNow)
83
 * @param withoutPrefix - Remove "in" or "ago" prefix (default: false)
84
 * @returns Relative time string
85
 */
86
toNow(withoutPrefix?: boolean): string;
87

88
/**
89
 * Get relative time from another moment
90
 * @param inp - Reference moment to compare against
91
 * @param suffix - Include "ago" or "in" suffix (default: true)
92
 * @returns Relative time string
93
 */
94
from(inp: MomentInput, suffix?: boolean): string;
95

96
/**
97
 * Get relative time to another moment (opposite of from)
98
 * @param inp - Reference moment to compare against
99
 * @param suffix - Include "ago" or "in" suffix (default: true)
100
 * @returns Relative time string
101
 */
102
to(inp: MomentInput, suffix?: boolean): string;
103
```
104

105
**Usage Examples:**
106

107
```javascript
108
import moment from "moment";
109

110
const now = moment();
111
const past = moment().subtract(2, "hours");
112
const future = moment().add(3, "days");
113

114
// Relative to now
115
console.log(past.fromNow()); // "2 hours ago"
116
console.log(past.fromNow(true)); // "2 hours" (without suffix)
117
console.log(future.fromNow()); // "in 3 days"
118

119
console.log(past.toNow()); // "in 2 hours"
120
console.log(future.toNow()); // "3 days ago"
121

122
// Relative to specific moment
123
const reference = moment("2023-12-25");
124
const target = moment("2023-12-28");
125
console.log(target.from(reference)); // "in 3 days"
126
console.log(target.to(reference)); // "3 days ago"
127
console.log(target.from(reference, false)); // "3 days" (without suffix)
128
```
129

130
### Calendar Time Formatting
131

132
Display dates in calendar format showing relationship to current week.
133

134
```javascript { .api }
135
/**
136
 * Get calendar time representation (relative to current week)
137
 * @returns Calendar string like "Today at 2:30 PM", "Last Monday at 2:30 PM"
138
 */
139
calendar(): string;
140

141
/**
142
 * Get calendar time with custom format specification
143
 * @param formats - Custom calendar format object
144
 * @returns Formatted calendar string
145
 */
146
calendar(formats: CalendarSpec): string;
147

148
/**
149
 * Get calendar time relative to specific reference time
150
 * @param time - Reference time to compare against (defaults to now)
151
 * @param formats - Optional custom format specification
152
 * @returns Formatted calendar string
153
 */
154
calendar(time: MomentInput, formats?: CalendarSpec): string;
155

156
interface CalendarSpec {
157
  sameDay?: CalendarSpecVal;     // Today
158
  nextDay?: CalendarSpecVal;     // Tomorrow
159
  lastDay?: CalendarSpecVal;     // Yesterday
160
  nextWeek?: CalendarSpecVal;    // Next week
161
  lastWeek?: CalendarSpecVal;    // Last week
162
  sameElse?: CalendarSpecVal;    // Everything else
163
  [x: string]: CalendarSpecVal | void; // Custom keys
164
}
165

166
type CalendarSpecVal = string | ((m?: MomentInput, now?: Moment) => string);
167
```
168

169
**Usage Examples:**
170

171
```javascript
172
import moment from "moment";
173

174
const now = moment();
175
const today = moment().hour(14).minute(30);
176
const yesterday = moment().subtract(1, "day").hour(10);
177
const tomorrow = moment().add(1, "day").hour(16);
178
const lastWeek = moment().subtract(7, "days");
179
const nextMonth = moment().add(1, "month");
180

181
// Default calendar formatting
182
console.log(today.calendar()); // "Today at 2:30 PM"
183
console.log(yesterday.calendar()); // "Yesterday at 10:00 AM"
184
console.log(tomorrow.calendar()); // "Tomorrow at 4:00 PM"
185
console.log(lastWeek.calendar()); // "Last Monday at 2:30 PM"
186
console.log(nextMonth.calendar()); // "01/25/2024"
187

188
// Custom calendar formats
189
const customFormats = {
190
  sameDay: "[Today] HH:mm",
191
  nextDay: "[Tomorrow] HH:mm", 
192
  lastDay: "[Yesterday] HH:mm",
193
  nextWeek: "dddd [at] HH:mm",
194
  lastWeek: "[Last] dddd [at] HH:mm",
195
  sameElse: "DD/MM/YYYY"
196
};
197

198
console.log(today.calendar(customFormats)); // "Today 14:30"
199
console.log(yesterday.calendar(customFormats)); // "Yesterday 10:00"
200

201
// Calendar relative to specific time
202
const reference = moment("2023-12-25T12:00:00");
203
const target = moment("2023-12-25T15:30:00");
204
console.log(target.calendar(reference)); // "Today at 3:30 PM"
205
```
206

207
### Numeric Representations
208

209
Methods for getting numeric representations of the moment.
210

211
```javascript { .api }
212
/**
213
 * Get Unix timestamp in milliseconds (same as +moment or moment.getTime())
214
 * @returns Milliseconds since Unix epoch
215
 */
216
valueOf(): number;
217

218
/**
219
 * Get Unix timestamp in seconds (not milliseconds)
220
 * @returns Seconds since Unix epoch
221
 */
222
unix(): number;
223

224
/**
225
 * Convert to native JavaScript Date object
226
 * @returns Native Date object
227
 */
228
toDate(): Date;
229

230
/**
231
 * Convert to array of date components
232
 * @returns Array of [year, month, day, hour, minute, second, millisecond]
233
 */
234
toArray(): number[];
235

236
/**
237
 * Convert to object with date components
238
 * @returns Object with date/time properties
239
 */
240
toObject(): MomentObjectOutput;
241

242
interface MomentObjectOutput {
243
  years: number;
244
  months: number;      // 0-indexed (0 = January)
245
  date: number;        // Day of month
246
  hours: number;
247
  minutes: number;
248
  seconds: number;
249
  milliseconds: number;
250
}
251
```
252

253
**Usage Examples:**
254

255
```javascript
256
import moment from "moment";
257

258
const date = moment("2023-12-25T15:30:45.123Z");
259

260
// Numeric representations
261
console.log(date.valueOf()); // 1703517045123 (milliseconds)
262
console.log(+date); // Same as valueOf()
263
console.log(date.unix()); // 1703517045 (seconds)
264

265
// Conversions
266
console.log(date.toDate()); // Native Date object
267
console.log(date.toArray()); // [2023, 11, 25, 15, 30, 45, 123]
268

269
const obj = date.toObject();
270
console.log(obj);
271
// {
272
//   years: 2023,
273
//   months: 11,    // December (0-indexed)
274
//   date: 25,
275
//   hours: 15,
276
//   minutes: 30,
277
//   seconds: 45,
278
//   milliseconds: 123
279
// }
280
```
281

282
### Localized Formatting
283

284
Formatting with locale-specific patterns and display names.
285

286
```javascript { .api }
287
/**
288
 * Get or set locale for this moment instance
289
 * @param locale - Locale identifier (when setting)
290
 * @returns Current locale string (when getting) or this moment (when setting)
291
 */
292
locale(): string;
293
locale(locale: LocaleSpecifier): Moment;
294

295
/**
296
 * Get locale data object for this moment's locale
297
 * @returns Locale data object with formatting functions and display names
298
 */
299
localeData(): Locale;
300

301
type LocaleSpecifier = string | Moment | Duration | string[] | boolean;
302
```
303

304
**Usage Examples:**
305

306
```javascript
307
import moment from "moment";
308

309
const date = moment("2023-12-25T15:30:00");
310

311
// Default locale formatting
312
console.log(date.format("LLLL")); // "Monday, December 25, 2023 3:30 PM"
313
console.log(date.format("dddd, MMMM Do YYYY")); // "Monday, December 25th 2023"
314

315
// Set locale for instance
316
const frenchDate = date.clone().locale("fr");
317
console.log(frenchDate.format("LLLL")); // "lundi 25 décembre 2023 15:30"
318
console.log(frenchDate.format("dddd, MMMM Do YYYY")); // "lundi, décembre 25e 2023"
319

320
// Multiple locales
321
const germanDate = date.clone().locale("de");
322
console.log(germanDate.format("LLLL")); // "Montag, 25. Dezember 2023 15:30"
323

324
// Get current locale
325
console.log(date.locale()); // "en"
326
console.log(frenchDate.locale()); // "fr"
327

328
// Locale data
329
const localeData = frenchDate.localeData();
330
console.log(localeData.months()); // French month names array
331
```
332

333
## Format Tokens
334

335
### Date Tokens
336

337
```javascript
338
// Year
339
YYYY    // 2023
340
YY      // 23
341

342
// Month
343
MM      // 01-12
344
MMM     // Jan, Feb, ..., Dec
345
MMMM    // January, February, ..., December
346
M       // 1-12
347

348
// Day of Month
349
DD      // 01-31
350
Do      // 1st, 2nd, 3rd, ..., 31st
351
D       // 1-31
352

353
// Day of Year
354
DDDD    // 001-365
355
DDD     // 1-365
356

357
// Day of Week
358
dddd    // Monday, Tuesday, ..., Sunday
359
ddd     // Mon, Tue, ..., Sun
360
dd      // Mo, Tu, ..., Su
361
d       // 0-6 (Sunday = 0)
362
e       // 0-6 (locale aware)
363
E       // 1-7 (ISO, Monday = 1)
364
```
365

366
### Time Tokens
367

368
```javascript
369
// Hour
370
HH      // 00-23
371
H       // 0-23
372
hh      // 01-12
373
h       // 1-12
374
kk      // 01-24
375
k       // 1-24
376

377
// Minute
378
mm      // 00-59
379
m       // 0-59
380

381
// Second
382
ss      // 00-59
383
s       // 0-59
384

385
// Fractional Second
386
SSS     // 000-999 (3 digits)
387
SS      // 00-99 (2 digits)
388
S       // 0-9 (1 digit)
389

390
// AM/PM
391
A       // AM, PM
392
a       // am, pm
393

394
// Timezone
395
Z       // +05:00, -08:00
396
ZZ      // +0500, -0800
397
```
398

399
### Week Tokens
400

401
```javascript
402
// Week of Year
403
ww      // 01-53 (locale aware)
404
w       // 1-53 (locale aware)
405
WW      // 01-53 (ISO week)
406
W       // 1-53 (ISO week)
407

408
// Week Year
409
gggg    // Week year (locale aware)
410
gg      // 2-digit week year (locale aware)
411
GGGG    // ISO week year
412
GG      // 2-digit ISO week year
413
```
414

415
### Locale-Aware Tokens
416

417
```javascript
418
// Locale-aware formatting (requires locale to be set)
419
LTS     // 8:30:25 PM
420
LT      // 8:30 PM
421
L       // 09/04/1986
422
LL      // September 4, 1986 
423
LLL     // September 4, 1986 8:30 PM
424
LLLL    // Monday, September 4, 1986 8:30 PM
425

426
// Lowercase versions
427
lts     // 8:30:25 pm
428
lt      // 8:30 pm
429
l       // 9/4/1986
430
ll      // Sep 4, 1986
431
lll     // Sep 4, 1986 8:30 pm
432
llll    // Mon, Sep 4, 1986 8:30 pm
433
```
434

435
### Escaping and Literals
436

437
```javascript
438
// Escape characters in square brackets
439
"[Today is] dddd"     // "Today is Monday"
440
"YYYY [escaped] YYYY" // "2023 escaped 2023"
441
"[Quarter] Q, YYYY"   // "Quarter 4, 2023"
442
```
443

444
**Format Examples:**
445

446
```javascript
447
import moment from "moment";
448

449
const date = moment("2023-12-25T15:30:45.123");
450

451
// Common formats
452
console.log(date.format("YYYY-MM-DD")); // "2023-12-25"
453
console.log(date.format("MM/DD/YYYY")); // "12/25/2023"
454
console.log(date.format("DD-MMM-YYYY")); // "25-Dec-2023"
455
console.log(date.format("dddd, MMMM Do, YYYY")); // "Monday, December 25th, 2023"
456

457
// Time formats
458
console.log(date.format("HH:mm:ss")); // "15:30:45"
459
console.log(date.format("h:mm A")); // "3:30 PM"
460
console.log(date.format("hh:mm:ss A")); // "03:30:45 PM"
461

462
// Combined formats
463
console.log(date.format("YYYY-MM-DD HH:mm:ss")); // "2023-12-25 15:30:45"
464
console.log(date.format("ddd, MMM Do YYYY, h:mm A")); // "Mon, Dec 25th 2023, 3:30 PM"
465

466
// With literals
467
console.log(date.format("[Today is] dddd [the] Do [of] MMMM"));
468
// "Today is Monday the 25th of December"
469
```