0
# Date and Time Objects
1

2
Core immutable date and time classes for representing temporal values in different calendar systems, with or without timezone information.
3

4
## Capabilities
5

6
### CalendarDate
7

8
Represents a date without time components in a specific calendar system.
9

10
```typescript { .api }
11
/**
12
 * A CalendarDate represents a date without any time components in a specific calendar system.
13
 */
14
class CalendarDate {
15
  constructor(year: number, month: number, day: number);
16
  constructor(era: string, year: number, month: number, day: number);
17
  constructor(calendar: Calendar, year: number, month: number, day: number);
18
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number);
19

20
  /** The calendar system associated with this date, e.g. Gregorian. */
21
  readonly calendar: Calendar;
22
  /** The calendar era for this date, e.g. "BC" or "AD". */
23
  readonly era: string;
24
  /** The year of this date within the era. */
25
  readonly year: number;
26
  /** The month number within the year. */
27
  readonly month: number;
28
  /** The day number within the month. */
29
  readonly day: number;
30

31
  /** Returns a copy of this date. */
32
  copy(): CalendarDate;
33
  /** Returns a new CalendarDate with the given duration added to it. */
34
  add(duration: DateDuration): CalendarDate;
35
  /** Returns a new CalendarDate with the given duration subtracted from it. */
36
  subtract(duration: DateDuration): CalendarDate;
37
  /** Returns a new CalendarDate with the given fields set to the provided values. */
38
  set(fields: DateFields): CalendarDate;
39
  /** Returns a new CalendarDate with the given field adjusted by a specified amount. */
40
  cycle(field: DateField, amount: number, options?: CycleOptions): CalendarDate;
41
  /** Converts the date to a native JavaScript Date object, with the time set to midnight in the given time zone. */
42
  toDate(timeZone: string): Date;
43
  /** Converts the date to an ISO 8601 formatted string. */
44
  toString(): string;
45
  /** Compares this date with another. A negative result indicates that this date is before the given one. */
46
  compare(b: AnyCalendarDate): number;
47
}
48
```
49

50
**Usage Examples:**
51

52
```typescript
53
import { CalendarDate, GregorianCalendar } from "@internationalized/date";
54

55
// Create dates using different constructors
56
const date1 = new CalendarDate(2024, 3, 15);
57
const date2 = new CalendarDate('AD', 2024, 3, 15);
58
const date3 = new CalendarDate(new GregorianCalendar(), 2024, 3, 15);
59

60
// Date arithmetic
61
const nextWeek = date1.add({ weeks: 1 });
62
const lastMonth = date1.subtract({ months: 1 });
63
const newYear = date1.set({ year: 2025 });
64

65
// Cycling fields
66
const nextDay = date1.cycle('day', 1);
67
const nextMonth = date1.cycle('month', 1);
68

69
// Conversion and comparison
70
const jsDate = date1.toDate('UTC');
71
const isoString = date1.toString(); // "2024-03-15"
72
const comparison = date1.compare(date2); // 0 (equal)
73
```
74

75
### CalendarDateTime
76

77
Represents a date with time components but without timezone information.
78

79
```typescript { .api }
80
/**
81
 * A CalendarDateTime represents a date with time components in a specific calendar system.
82
 */
83
class CalendarDateTime {
84
  constructor(year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
85
  constructor(era: string, year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
86
  constructor(calendar: Calendar, year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
87
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number, hour?: number, minute?: number, second?: number, millisecond?: number);
88

89
  /** The calendar system associated with this date, e.g. Gregorian. */
90
  readonly calendar: Calendar;
91
  /** The calendar era for this date, e.g. "BC" or "AD". */
92
  readonly era: string;
93
  /** The year of this date within the era. */
94
  readonly year: number;
95
  /** The month number within the year. */
96
  readonly month: number;
97
  /** The day number within the month. */
98
  readonly day: number;
99
  /** The hour in the day, numbered from 0 to 23. */
100
  readonly hour: number;
101
  /** The minute in the hour. */
102
  readonly minute: number;
103
  /** The second in the minute. */
104
  readonly second: number;
105
  /** The millisecond in the second. */
106
  readonly millisecond: number;
107

108
  /** Returns a copy of this date. */
109
  copy(): CalendarDateTime;
110
  /** Returns a new CalendarDateTime with the given duration added to it. */
111
  add(duration: DateTimeDuration): CalendarDateTime;
112
  /** Returns a new CalendarDateTime with the given duration subtracted from it. */
113
  subtract(duration: DateTimeDuration): CalendarDateTime;
114
  /** Returns a new CalendarDateTime with the given fields set to the provided values. */
115
  set(fields: DateFields | TimeFields): CalendarDateTime;
116
  /** Returns a new CalendarDateTime with the given field adjusted by a specified amount. */
117
  cycle(field: DateField | TimeField, amount: number, options?: CycleOptions | CycleTimeOptions): CalendarDateTime;
118
  /** Converts the date to a native JavaScript Date object in the given time zone. */
119
  toDate(timeZone: string): Date;
120
  /** Converts the date to an ISO 8601 formatted string. */
121
  toString(): string;
122
  /** Compares this date with another. A negative result indicates that this date is before the given one. */
123
  compare(b: AnyDateTime): number;
124
}
125
```
126

127
### Time
128

129
Represents a time without date or timezone information.
130

131
```typescript { .api }
132
/**
133
 * A Time represents a time without any date or timezone components.
134
 */
135
class Time {
136
  constructor(hour?: number, minute?: number, second?: number, millisecond?: number);
137

138
  /** The hour, numbered from 0 to 23. */
139
  readonly hour: number;
140
  /** The minute in the hour. */
141
  readonly minute: number;
142
  /** The second in the minute. */
143
  readonly second: number;
144
  /** The millisecond in the second. */
145
  readonly millisecond: number;
146

147
  /** Returns a copy of this time. */
148
  copy(): Time;
149
  /** Returns a new Time with the given duration added to it. */
150
  add(duration: TimeDuration): Time;
151
  /** Returns a new Time with the given duration subtracted from it. */
152
  subtract(duration: TimeDuration): Time;
153
  /** Returns a new Time with the given fields set to the provided values. */
154
  set(fields: TimeFields): Time;
155
  /** Returns a new Time with the given field adjusted by a specified amount. */
156
  cycle(field: TimeField, amount: number, options?: CycleTimeOptions): Time;
157
  /** Converts the time to an ISO 8601 formatted string. */
158
  toString(): string;
159
  /** Compares this time with another. A negative result indicates that this time is before the given one. */
160
  compare(b: AnyTime): number;
161
}
162
```
163

164
**Usage Examples:**
165

166
```typescript
167
import { Time } from "@internationalized/date";
168

169
// Create time objects
170
const time = new Time(14, 30);
171
const preciseTime = new Time(9, 15, 30, 750);
172

173
// Time arithmetic
174
const laterTime = time.add({ hours: 2, minutes: 15 });
175
const earlierTime = time.subtract({ minutes: 30 });
176

177
// Set specific fields
178
const newTime = time.set({ hour: 12, minute: 0 });
179
const resetSeconds = time.set({ second: 0, millisecond: 0 });
180

181
// Cycle time with options
182
const nextHour = time.cycle('hour', 1);
183
const nextHour12 = time.cycle('hour', 1, { hourCycle: 12 });
184

185
// String representation
186
const timeString = time.toString(); // "14:30:00"
187
```
188

189
### ZonedDateTime
190

191
Represents a date and time in a specific timezone and calendar system.
192

193
```typescript { .api }
194
/**
195
 * A ZonedDateTime represents a date and time in a specific time zone and calendar system.
196
 */
197
class ZonedDateTime {
198
  constructor(year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
199
  constructor(era: string, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
200
  constructor(calendar: Calendar, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
201
  constructor(calendar: Calendar, era: string, year: number, month: number, day: number, timeZone: string, offset: number, hour?: number, minute?: number, second?: number, millisecond?: number);
202

203
  /** The calendar system associated with this date, e.g. Gregorian. */
204
  readonly calendar: Calendar;
205
  /** The calendar era for this date, e.g. "BC" or "AD". */
206
  readonly era: string;
207
  /** The year of this date within the era. */
208
  readonly year: number;
209
  /** The month number within the year. */
210
  readonly month: number;
211
  /** The day number within the month. */
212
  readonly day: number;
213
  /** The hour in the day, numbered from 0 to 23. */
214
  readonly hour: number;
215
  /** The minute in the hour. */
216
  readonly minute: number;
217
  /** The second in the minute. */
218
  readonly second: number;
219
  /** The millisecond in the second. */
220
  readonly millisecond: number;
221
  /** The IANA time zone identifier that this date and time is represented in. */
222
  readonly timeZone: string;
223
  /** The UTC offset for this time, in milliseconds. */
224
  readonly offset: number;
225

226
  /** Returns a copy of this date. */
227
  copy(): ZonedDateTime;
228
  /** Returns a new ZonedDateTime with the given duration added to it. */
229
  add(duration: DateTimeDuration): ZonedDateTime;
230
  /** Returns a new ZonedDateTime with the given duration subtracted from it. */
231
  subtract(duration: DateTimeDuration): ZonedDateTime;
232
  /** Returns a new ZonedDateTime with the given fields set to the provided values. */
233
  set(fields: DateFields & TimeFields, disambiguation?: Disambiguation): ZonedDateTime;
234
  /** Returns a new ZonedDateTime with the given field adjusted by a specified amount. */
235
  cycle(field: DateField | TimeField, amount: number, options?: CycleTimeOptions): ZonedDateTime;
236
  /** Converts the date to a native JavaScript Date object. */
237
  toDate(): Date;
238
  /** Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier. */
239
  toString(): string;
240
  /** Converts the date to an ISO 8601 formatted string in UTC. */
241
  toAbsoluteString(): string;
242
  /** Compares this date with another. */
243
  compare(b: CalendarDate | CalendarDateTime | ZonedDateTime): number;
244
}
245
```
246

247
**Usage Examples:**
248

249
```typescript
250
import { ZonedDateTime } from "@internationalized/date";
251

252
// Create zoned datetime objects
253
const zonedDT = new ZonedDateTime(2024, 3, 15, 'America/New_York', -5 * 60 * 60 * 1000, 14, 30);
254
const utcTime = new ZonedDateTime(2024, 3, 15, 'UTC', 0, 19, 30);
255

256
// Timezone-aware arithmetic (handles DST)
257
const nextDay = zonedDT.add({ days: 1 });
258
const nextHour = zonedDT.add({ hours: 1 });
259

260
// Set fields with disambiguation for DST
261
const newTime = zonedDT.set({ hour: 2, minute: 30 }, 'later');
262

263
// Different string representations
264
const withOffset = zonedDT.toString(); // "2024-03-15T14:30:00-05:00[America/New_York]"
265
const utcString = zonedDT.toAbsoluteString(); // "2024-03-15T19:30:00.000Z"
266

267
// Convert to JavaScript Date
268
const jsDate = zonedDT.toDate();
269
```
270

271
## Types
272

273
```typescript { .api }
274
interface DateFields {
275
  era?: string;
276
  year?: number;
277
  month?: number;
278
  day?: number;
279
}
280

281
interface TimeFields {
282
  hour?: number;
283
  minute?: number;
284
  second?: number;
285
  millisecond?: number;
286
}
287

288
type DateField = keyof DateFields;
289
type TimeField = keyof TimeFields;
290

291
interface CycleOptions {
292
  /** Whether to round the field value to the nearest interval of the amount. */
293
  round?: boolean;
294
}
295

296
interface CycleTimeOptions extends CycleOptions {
297
  /**
298
   * Whether to use 12 or 24 hour time. If 12 hour time is chosen, the resulting value
299
   * will remain in the same day period as the original value.
300
   * @default 24
301
   */
302
  hourCycle?: 12 | 24;
303
}
304
```