0
# DateTime API
1

2
The DateTime class is Luxon's primary date and time representation. It provides comprehensive functionality for creating, parsing, formatting, and manipulating dates and times with full timezone and locale support.
3

4
## Capabilities
5

6
### Static Factory Methods
7

8
Methods for creating DateTime instances from various sources.
9

10
```javascript { .api }
11
/**
12
 * Current instant in the system's timezone
13
 */
14
static now(): DateTime;
15

16
/**
17
 * Create a DateTime in the local timezone
18
 * @param year - Calendar year
19
 * @param month - Calendar month (1-12)
20
 * @param day - Day of month
21
 * @param hour - Hour (0-23)
22
 * @param minute - Minute (0-59)
23
 * @param second - Second (0-59)
24
 * @param millisecond - Millisecond (0-999)
25
 * @param opts - Options including zone, locale, numberingSystem
26
 */
27
static local(year?, month?, day?, hour?, minute?, second?, millisecond?, opts?): DateTime;
28

29
/**
30
 * Create a DateTime in UTC
31
 */
32
static utc(year?, month?, day?, hour?, minute?, second?, millisecond?, opts?): DateTime;
33

34
/**
35
 * Create from JavaScript Date object
36
 * @param date - JavaScript Date
37
 * @param opts - Options including zone and locale
38
 */
39
static fromJSDate(date: Date, opts?): DateTime;
40

41
/**
42
 * Create from epoch milliseconds
43
 * @param milliseconds - Milliseconds since Unix epoch
44
 * @param opts - Options including zone and locale
45
 */
46
static fromMillis(milliseconds: number, opts?): DateTime;
47

48
/**
49
 * Create from epoch seconds
50
 * @param seconds - Seconds since Unix epoch
51
 * @param opts - Options including zone and locale
52
 */
53
static fromSeconds(seconds: number, opts?): DateTime;
54

55
/**
56
 * Create from object with date/time properties
57
 * @param obj - Object with year, month, day, etc. properties
58
 * @param opts - Options including zone and locale
59
 */
60
static fromObject(obj: object, opts?): DateTime;
61
```
62

63
### String Parsing Methods
64

65
Methods for parsing DateTime from various string formats.
66

67
```javascript { .api }
68
/**
69
 * Parse from ISO 8601 string
70
 * @param text - ISO 8601 formatted string
71
 * @param opts - Parsing options including zone and setZone
72
 */
73
static fromISO(text: string, opts?): DateTime;
74

75
/**
76
 * Parse from RFC 2822 string
77
 * @param text - RFC 2822 formatted string
78
 * @param opts - Parsing options
79
 */
80
static fromRFC2822(text: string, opts?): DateTime;
81

82
/**
83
 * Parse from HTTP header date string
84
 * @param text - HTTP date string
85
 * @param opts - Parsing options
86
 */
87
static fromHTTP(text: string, opts?): DateTime;
88

89
/**
90
 * Parse from custom format string
91
 * @param text - Date string to parse
92
 * @param fmt - Format pattern using Luxon tokens
93
 * @param opts - Parsing options including locale
94
 */
95
static fromFormat(text: string, fmt: string, opts?): DateTime;
96

97
/**
98
 * Parse from SQL date/time string
99
 * @param text - SQL formatted string
100
 * @param opts - Parsing options
101
 */
102
static fromSQL(text: string, opts?): DateTime;
103
```
104

105
### Static Utility Methods
106

107
```javascript { .api }
108
/**
109
 * Create an invalid DateTime
110
 * @param reason - Reason for invalidity
111
 * @param explanation - Additional explanation
112
 */
113
static invalid(reason: string, explanation?: string): DateTime;
114

115
/**
116
 * Check if object is a DateTime instance
117
 * @param o - Object to check
118
 */
119
static isDateTime(o: any): boolean;
120

121
/**
122
 * Return the minimum DateTime from arguments
123
 * @param dateTimes - DateTime instances to compare
124
 */
125
static min(...dateTimes: DateTime[]): DateTime;
126

127
/**
128
 * Return the maximum DateTime from arguments
129
 * @param dateTimes - DateTime instances to compare
130
 */
131
static max(...dateTimes: DateTime[]): DateTime;
132

133
/**
134
 * Explain how format parsing would work
135
 * @param text - Text to parse
136
 * @param fmt - Format pattern
137
 * @param opts - Options
138
 */
139
static fromFormatExplain(text: string, fmt: string, opts?): object;
140

141
/**
142
 * @deprecated Use fromFormat instead
143
 * Parse from custom format string  
144
 * @param text - Text to parse
145
 * @param fmt - Format pattern
146
 * @param opts - Parsing options
147
 */
148
static fromString(text: string, fmt: string, opts?): DateTime;
149

150
/**
151
 * @deprecated Use fromFormatExplain instead
152
 * Explain how string parsing would work
153
 * @param text - Text to parse
154
 * @param fmt - Format pattern
155
 * @param opts - Options
156
 */
157
static fromStringExplain(text: string, fmt: string, opts?): object;
158
```
159

160
### Instance Properties
161

162
Access date/time components and metadata.
163

164
```javascript { .api }
165
// Validation
166
isValid: boolean;
167
invalidReason: string | null;
168
invalidExplanation: string | null;
169

170
// Locale settings
171
locale: string;
172
numberingSystem: string;
173
outputCalendar: string;
174

175
// Timezone
176
zone: Zone;
177
zoneName: string;
178
offset: number;
179
offsetNameShort: string;
180
offsetNameLong: string;
181
isOffsetFixed: boolean;
182
isInDST: boolean;
183

184
// Calendar components
185
year: number;
186
quarter: number;  // 1-4
187
month: number;    // 1-12
188
day: number;
189
hour: number;     // 0-23
190
minute: number;   // 0-59
191
second: number;   // 0-59
192
millisecond: number; // 0-999
193

194
// Week-based components
195
weekYear: number;
196
weekNumber: number;
197
weekday: number;  // 1-7, Monday=1
198
ordinal: number;  // Day of year
199

200
// Localized names
201
monthShort: string;
202
monthLong: string;
203
weekdayShort: string;
204
weekdayLong: string;
205

206
// Calendar calculations
207
isInLeapYear: boolean;
208
daysInMonth: number;
209
daysInYear: number;
210
weeksInWeekYear: number;
211
```
212

213
### Instance Methods
214

215
#### Configuration and Timezone
216

217
```javascript { .api }
218
/**
219
 * Get value of specific unit
220
 * @param unit - Unit name (year, month, day, etc.)
221
 */
222
get(unit: string): number;
223

224
/**
225
 * Get resolved Intl options used for formatting
226
 * @param opts - Format options to resolve
227
 */
228
resolvedLocaleOptions(opts?): object;
229

230
/**
231
 * Convert to UTC
232
 * @param offset - Specific offset or options
233
 * @param opts - Additional options
234
 */
235
toUTC(offset?: number, opts?): DateTime;
236

237
/**
238
 * Convert to local timezone
239
 */
240
toLocal(): DateTime;
241

242
/**
243
 * Set timezone
244
 * @param zone - Zone name or Zone instance
245
 * @param opts - Options including keepLocalTime
246
 */
247
setZone(zone: string | Zone, opts?): DateTime;
248

249
/**
250
 * Reconfigure locale settings
251
 * @param opts - Locale, numberingSystem, outputCalendar
252
 */
253
reconfigure(opts: {locale?, numberingSystem?, outputCalendar?}): DateTime;
254

255
/**
256
 * Set locale
257
 * @param locale - Locale string
258
 */
259
setLocale(locale: string): DateTime;
260
```
261

262
#### Manipulation
263

264
```javascript { .api }
265
/**
266
 * Set specific date/time values
267
 * @param values - Object with date/time properties to set
268
 */
269
set(values: object): DateTime;
270

271
/**
272
 * Add duration
273
 * @param duration - Duration to add or object with duration units
274
 */
275
plus(duration: Duration | object): DateTime;
276

277
/**
278
 * Subtract duration
279
 * @param duration - Duration to subtract or object with duration units
280
 */
281
minus(duration: Duration | object): DateTime;
282

283
/**
284
 * Go to start of time unit
285
 * @param unit - Unit (year, month, week, day, hour, minute, second)
286
 */
287
startOf(unit: string): DateTime;
288

289
/**
290
 * Go to end of time unit
291
 * @param unit - Unit (year, month, week, day, hour, minute, second)
292
 */
293
endOf(unit: string): DateTime;
294
```
295

296
#### Formatting
297

298
```javascript { .api }
299
/**
300
 * Format with custom format string
301
 * @param fmt - Format pattern using Luxon tokens
302
 * @param opts - Options including locale
303
 */
304
toFormat(fmt: string, opts?): string;
305

306
/**
307
 * Format using Intl.DateTimeFormat
308
 * @param formatOpts - Intl.DateTimeFormat options
309
 * @param opts - Additional options
310
 */
311
toLocaleString(formatOpts?, opts?): string;
312

313
/**
314
 * Get Intl.DateTimeFormat parts
315
 * @param opts - Intl.DateTimeFormat options
316
 */
317
toLocaleParts(opts?): object[];
318

319
/**
320
 * ISO 8601 string
321
 * @param opts - Options for suppressing fields and format
322
 */
323
toISO(opts?): string;
324

325
/**
326
 * ISO 8601 date string (YYYY-MM-DD)
327
 * @param opts - Options
328
 */
329
toISODate(opts?): string;
330

331
/**
332
 * ISO 8601 week date string
333
 */
334
toISOWeekDate(): string;
335

336
/**
337
 * ISO 8601 time string
338
 * @param opts - Options for suppressing fields
339
 */
340
toISOTime(opts?): string;
341

342
/**
343
 * RFC 2822 string
344
 */
345
toRFC2822(): string;
346

347
/**
348
 * HTTP header date string
349
 */
350
toHTTP(): string;
351

352
/**
353
 * SQL date string (YYYY-MM-DD)
354
 */
355
toSQLDate(): string;
356

357
/**
358
 * SQL time string
359
 * @param opts - Options including includeZone
360
 */
361
toSQLTime(opts?): string;
362

363
/**
364
 * SQL datetime string
365
 * @param opts - Options including includeZone
366
 */
367
toSQL(opts?): string;
368
```
369

370
#### Conversion
371

372
```javascript { .api }
373
/**
374
 * String representation (ISO format)
375
 */
376
toString(): string;
377

378
/**
379
 * Epoch milliseconds (for sorting/comparison)
380
 */
381
valueOf(): number;
382

383
/**
384
 * Epoch milliseconds
385
 */
386
toMillis(): number;
387

388
/**
389
 * Epoch seconds
390
 */
391
toSeconds(): number;
392

393
/**
394
 * Epoch seconds as integer
395
 */
396
toUnixInteger(): number;
397

398
/**
399
 * JSON representation (ISO string)
400
 */
401
toJSON(): string;
402

403
/**
404
 * BSON representation (JavaScript Date)
405
 */
406
toBSON(): Date;
407

408
/**
409
 * JavaScript object with date/time properties
410
 * @param opts - Options including includeConfig
411
 */
412
toObject(opts?): object;
413

414
/**
415
 * JavaScript Date object
416
 */
417
toJSDate(): Date;
418
```
419

420
#### Comparison and Difference
421

422
```javascript { .api }
423
/**
424
 * Difference from other DateTime
425
 * @param otherDateTime - DateTime to compare against
426
 * @param unit - Unit or array of units for difference
427
 * @param opts - Options including conversionAccuracy
428
 */
429
diff(otherDateTime: DateTime, unit?: string | string[], opts?): Duration;
430

431
/**
432
 * Difference from current time
433
 * @param unit - Unit or array of units for difference
434
 * @param opts - Options including conversionAccuracy
435
 */
436
diffNow(unit?: string | string[], opts?): Duration;
437

438
/**
439
 * Create interval until other DateTime
440
 * @param otherDateTime - End DateTime
441
 */
442
until(otherDateTime: DateTime): Interval;
443

444
/**
445
 * Check if same time unit as other DateTime
446
 * @param otherDateTime - DateTime to compare
447
 * @param unit - Unit to compare (year, month, day, etc.)
448
 */
449
hasSame(otherDateTime: DateTime, unit: string): boolean;
450

451
/**
452
 * Check equality with other DateTime
453
 * @param other - DateTime to compare
454
 */
455
equals(other: DateTime): boolean;
456
```
457

458
#### Relative Formatting
459

460
```javascript { .api }
461
/**
462
 * Relative time string (e.g., "3 hours ago")
463
 * @param opts - Options including base DateTime, style, unit, locale
464
 */
465
toRelative(opts?): string;
466

467
/**
468
 * Relative calendar string (e.g., "tomorrow at 3:00 PM")
469
 * @param opts - Options including base DateTime, locale
470
 */
471
toRelativeCalendar(opts?): string;
472
```
473

474
### Format Preset Constants
475

476
Pre-defined format options for common date/time representations.
477

478
```javascript { .api }
479
// Date formats
480
static DATE_SHORT: object;        // 10/14/1983
481
static DATE_MED: object;          // Oct 14, 1983
482
static DATE_MED_WITH_WEEKDAY: object; // Fri, Oct 14, 1983
483
static DATE_FULL: object;         // October 14, 1983
484
static DATE_HUGE: object;         // Tuesday, October 14, 1983
485

486
// Time formats
487
static TIME_SIMPLE: object;       // 09:30 AM
488
static TIME_WITH_SECONDS: object; // 09:30:23 AM
489
static TIME_WITH_SHORT_OFFSET: object; // 09:30:23 AM EDT
490
static TIME_WITH_LONG_OFFSET: object;  // 09:30:23 AM Eastern Daylight Time
491
static TIME_24_SIMPLE: object;    // 09:30
492
static TIME_24_WITH_SECONDS: object; // 09:30:23
493
static TIME_24_WITH_SHORT_OFFSET: object; // 09:30:23 EDT
494
static TIME_24_WITH_LONG_OFFSET: object;  // 09:30:23 Eastern Daylight Time
495

496
// DateTime formats
497
static DATETIME_SHORT: object;    // 10/14/1983, 9:30 AM
498
static DATETIME_SHORT_WITH_SECONDS: object; // 10/14/1983, 9:30:33 AM
499
static DATETIME_MED: object;      // Oct 14, 1983, 9:30 AM
500
static DATETIME_MED_WITH_SECONDS: object; // Oct 14, 1983, 9:30:33 AM
501
static DATETIME_MED_WITH_WEEKDAY: object; // Fri, 14 Oct 1983, 9:30 AM
502
static DATETIME_FULL: object;     // October 14, 1983, 9:30 AM EDT
503
static DATETIME_FULL_WITH_SECONDS: object; // October 14, 1983, 9:30:33 AM EDT
504
static DATETIME_HUGE: object;     // Friday, October 14, 1983, 9:30 AM Eastern Daylight Time
505
static DATETIME_HUGE_WITH_SECONDS: object; // Friday, October 14, 1983, 9:30:33 AM Eastern Daylight Time
506
```
507

508
## Usage Examples
509

510
```javascript
511
import { DateTime } from "luxon";
512

513
// Creating DateTimes
514
const now = DateTime.now();
515
const specific = DateTime.local(2023, 12, 25, 10, 30);
516
const fromString = DateTime.fromISO("2023-12-25T10:30:00");
517

518
// Formatting
519
console.log(now.toFormat("yyyy-MM-dd HH:mm")); // "2023-10-25 14:30"
520
console.log(now.toLocaleString(DateTime.DATE_MED)); // "Oct 25, 2023"
521

522
// Manipulation
523
const tomorrow = now.plus({ days: 1 });
524
const startOfDay = now.startOf('day');
525
const endOfMonth = now.endOf('month');
526

527
// Timezone conversion
528
const utc = now.toUTC();
529
const ny = now.setZone('America/New_York');
530

531
// Comparisons
532
const diff = tomorrow.diff(now, 'hours');
533
console.log(diff.hours); // 24
534

535
const isAfter = tomorrow > now; // true
536
const isSameDay = now.hasSame(tomorrow.minus({ hours: 12 }), 'day');
537
```