0
# Calendar Systems
1

2
Support for 13 international calendar systems including Gregorian, Buddhist, Islamic, Hebrew, Persian, and others with factory creation and consistent APIs.
3

4
## Capabilities
5

6
### Calendar Factory
7

8
Creates calendar instances from identifier strings for use with date objects.
9

10
```typescript { .api }
11
/**
12
 * Factory function to create calendar instances from identifier strings
13
 * @param identifier - Calendar system identifier
14
 * @returns Calendar implementation instance
15
 */
16
function createCalendar(identifier: CalendarIdentifier): Calendar;
17

18
type CalendarIdentifier = 'gregory' | 'buddhist' | 'chinese' | 'coptic' | 'dangi' | 
19
  'ethioaa' | 'ethiopic' | 'hebrew' | 'indian' | 'islamic' | 'islamic-umalqura' | 
20
  'islamic-tbla' | 'islamic-civil' | 'islamic-rgsa' | 'iso8601' | 'japanese' | 'persian' | 'roc';
21
```
22

23
**Usage Examples:**
24

25
```typescript
26
import { createCalendar, CalendarDate } from "@internationalized/date";
27

28
// Create different calendar systems
29
const gregorian = createCalendar('gregory');
30
const buddhist = createCalendar('buddhist');
31
const persian = createCalendar('persian');
32
const islamic = createCalendar('islamic-civil');
33

34
// Use with date objects
35
const gregorianDate = new CalendarDate(gregorian, 2024, 3, 15);
36
const buddhistDate = new CalendarDate(buddhist, 2567, 3, 15); // Buddhist year
37
const persianDate = new CalendarDate(persian, 1403, 1, 26); // Persian year
38
```
39

40
### GregorianCalendar
41

42
Standard Gregorian calendar implementation used worldwide.
43

44
```typescript { .api }
45
/**
46
 * Standard Gregorian calendar implementation
47
 */
48
class GregorianCalendar implements Calendar {
49
  identifier: 'gregory';
50
  
51
  fromJulianDay(jd: number): CalendarDate;
52
  toJulianDay(date: AnyCalendarDate): number;
53
  getDaysInMonth(date: AnyCalendarDate): number;
54
  getMonthsInYear(date: AnyCalendarDate): number;
55
  getYearsInEra(date: AnyCalendarDate): number;
56
  getEras(): string[];
57
}
58
```
59

60
**Usage Examples:**
61

62
```typescript
63
import { GregorianCalendar, CalendarDate } from "@internationalized/date";
64

65
const gregorian = new GregorianCalendar();
66
const date = new CalendarDate(gregorian, 2024, 3, 15);
67

68
// Calendar operations
69
const daysInMarch = gregorian.getDaysInMonth(date); // 31
70
const monthsInYear = gregorian.getMonthsInYear(date); // 12
71
const eras = gregorian.getEras(); // ['BC', 'AD']
72
```
73

74
### JapaneseCalendar
75

76
Japanese calendar with imperial eras support.
77

78
```typescript { .api }
79
/**
80
 * Japanese calendar with imperial eras
81
 */
82
class JapaneseCalendar implements Calendar {
83
  identifier: 'japanese';
84
  
85
  fromJulianDay(jd: number): CalendarDate;
86
  toJulianDay(date: AnyCalendarDate): number;
87
  getDaysInMonth(date: AnyCalendarDate): number;
88
  getMonthsInYear(date: AnyCalendarDate): number;
89
  getYearsInEra(date: AnyCalendarDate): number;
90
  getEras(): string[];
91
}
92
```
93

94
**Usage Examples:**
95

96
```typescript
97
import { JapaneseCalendar, CalendarDate } from "@internationalized/date";
98

99
const japanese = new JapaneseCalendar();
100
// Current Reiwa era (started 2019)
101
const reiwDate = new CalendarDate(japanese, 'reiwa', 6, 3, 15); // Reiwa 6 (2024)
102

103
const eras = japanese.getEras(); // ['meiji', 'taisho', 'showa', 'heisei', 'reiwa']
104
```
105

106
### BuddhistCalendar
107

108
Buddhist calendar system used in Thailand and other Buddhist countries.
109

110
```typescript { .api }
111
/**
112
 * Buddhist calendar system
113
 */
114
class BuddhistCalendar implements Calendar {
115
  identifier: 'buddhist';
116
  
117
  fromJulianDay(jd: number): CalendarDate;
118
  toJulianDay(date: AnyCalendarDate): number;
119
  getDaysInMonth(date: AnyCalendarDate): number;
120
  getMonthsInYear(date: AnyCalendarDate): number;
121
  getYearsInEra(date: AnyCalendarDate): number;
122
  getEras(): string[];
123
}
124
```
125

126
**Usage Examples:**
127

128
```typescript
129
import { BuddhistCalendar, CalendarDate } from "@internationalized/date";
130

131
const buddhist = new BuddhistCalendar();
132
// Buddhist era is ~543 years ahead of Gregorian
133
const buddhistDate = new CalendarDate(buddhist, 2567, 3, 15); // BE 2567 = 2024 CE
134
```
135

136
### TaiwanCalendar
137

138
Republic of China calendar used in Taiwan.
139

140
```typescript { .api }
141
/**
142
 * Republic of China calendar
143
 */
144
class TaiwanCalendar implements Calendar {
145
  identifier: 'roc';
146
  
147
  fromJulianDay(jd: number): CalendarDate;
148
  toJulianDay(date: AnyCalendarDate): number;
149
  getDaysInMonth(date: AnyCalendarDate): number;
150
  getMonthsInYear(date: AnyCalendarDate): number;
151
  getYearsInEra(date: AnyCalendarDate): number;
152
  getEras(): string[];
153
}
154
```
155

156
### PersianCalendar
157

158
Persian/Iranian solar calendar (Jalali calendar).
159

160
```typescript { .api }
161
/**
162
 * Persian/Iranian solar calendar
163
 */
164
class PersianCalendar implements Calendar {
165
  identifier: 'persian';
166
  
167
  fromJulianDay(jd: number): CalendarDate;
168
  toJulianDay(date: AnyCalendarDate): number;
169
  getDaysInMonth(date: AnyCalendarDate): number;
170
  getMonthsInYear(date: AnyCalendarDate): number;
171
  getYearsInEra(date: AnyCalendarDate): number;
172
  getEras(): string[];
173
}
174
```
175

176
**Usage Examples:**
177

178
```typescript
179
import { PersianCalendar, CalendarDate } from "@internationalized/date";
180

181
const persian = new PersianCalendar();
182
const persianDate = new CalendarDate(persian, 1403, 1, 26); // Persian New Year area
183
```
184

185
### IndianCalendar
186

187
Indian National Calendar (Saka calendar).
188

189
```typescript { .api }
190
/**
191
 * Indian National Calendar
192
 */
193
class IndianCalendar implements Calendar {
194
  identifier: 'indian';
195
  
196
  fromJulianDay(jd: number): CalendarDate;
197
  toJulianDay(date: AnyCalendarDate): number;
198
  getDaysInMonth(date: AnyCalendarDate): number;
199
  getMonthsInYear(date: AnyCalendarDate): number;
200
  getYearsInEra(date: AnyCalendarDate): number;
201
  getEras(): string[];
202
}
203
```
204

205
### Islamic Calendar Variants
206

207
Multiple implementations of the Islamic calendar with different calculation methods.
208

209
```typescript { .api }
210
/**
211
 * Islamic civil calendar variant
212
 */
213
class IslamicCivilCalendar implements Calendar {
214
  identifier: 'islamic-civil';
215
  
216
  fromJulianDay(jd: number): CalendarDate;
217
  toJulianDay(date: AnyCalendarDate): number;
218
  getDaysInMonth(date: AnyCalendarDate): number;
219
  getMonthsInYear(date: AnyCalendarDate): number;
220
  getYearsInEra(date: AnyCalendarDate): number;
221
  getEras(): string[];
222
}
223

224
/**
225
 * Islamic tabular calendar variant
226
 */
227
class IslamicTabularCalendar implements Calendar {
228
  identifier: 'islamic-tbla';
229
  
230
  fromJulianDay(jd: number): CalendarDate;
231
  toJulianDay(date: AnyCalendarDate): number;
232
  getDaysInMonth(date: AnyCalendarDate): number;
233
  getMonthsInYear(date: AnyCalendarDate): number;
234
  getYearsInEra(date: AnyCalendarDate): number;
235
  getEras(): string[];
236
}
237

238
/**
239
 * Islamic Umalqura calendar (Saudi Arabia)
240
 */
241
class IslamicUmalquraCalendar implements Calendar {
242
  identifier: 'islamic-umalqura';
243
  
244
  fromJulianDay(jd: number): CalendarDate;
245
  toJulianDay(date: AnyCalendarDate): number;
246
  getDaysInMonth(date: AnyCalendarDate): number;
247
  getMonthsInYear(date: AnyCalendarDate): number;
248
  getYearsInEra(date: AnyCalendarDate): number;
249
  getEras(): string[];
250
}
251
```
252

253
**Usage Examples:**
254

255
```typescript
256
import { 
257
  IslamicCivilCalendar, 
258
  IslamicUmalquraCalendar, 
259
  CalendarDate 
260
} from "@internationalized/date";
261

262
const islamicCivil = new IslamicCivilCalendar();
263
const islamicUmalqura = new IslamicUmalquraCalendar();
264

265
const civilDate = new CalendarDate(islamicCivil, 1445, 9, 15);
266
const umalquraDate = new CalendarDate(islamicUmalqura, 1445, 9, 15);
267
```
268

269
### HebrewCalendar
270

271
Hebrew/Jewish calendar with lunar months and leap years.
272

273
```typescript { .api }
274
/**
275
 * Hebrew/Jewish calendar
276
 */
277
class HebrewCalendar implements Calendar {
278
  identifier: 'hebrew';
279
  
280
  fromJulianDay(jd: number): CalendarDate;
281
  toJulianDay(date: AnyCalendarDate): number;
282
  getDaysInMonth(date: AnyCalendarDate): number;
283
  getMonthsInYear(date: AnyCalendarDate): number;
284
  getYearsInEra(date: AnyCalendarDate): number;
285
  getEras(): string[];
286
}
287
```
288

289
### Ethiopian Calendar Variants
290

291
Ethiopian calendar systems including Coptic variant.
292

293
```typescript { .api }
294
/**
295
 * Ethiopian calendar
296
 */
297
class EthiopicCalendar implements Calendar {
298
  identifier: 'ethiopic';
299
  
300
  fromJulianDay(jd: number): CalendarDate;
301
  toJulianDay(date: AnyCalendarDate): number;
302
  getDaysInMonth(date: AnyCalendarDate): number;
303
  getMonthsInYear(date: AnyCalendarDate): number;
304
  getYearsInEra(date: AnyCalendarDate): number;
305
  getEras(): string[];
306
}
307

308
/**
309
 * Ethiopic Amete Alem calendar variant
310
 */
311
class EthiopicAmeteAlemCalendar implements Calendar {
312
  identifier: 'ethioaa';
313
  
314
  fromJulianDay(jd: number): CalendarDate;
315
  toJulianDay(date: AnyCalendarDate): number;
316
  getDaysInMonth(date: AnyCalendarDate): number;
317
  getMonthsInYear(date: AnyCalendarDate): number;
318
  getYearsInEra(date: AnyCalendarDate): number;
319
  getEras(): string[];
320
}
321

322
/**
323
 * Coptic calendar system
324
 */
325
class CopticCalendar implements Calendar {
326
  identifier: 'coptic';
327
  
328
  fromJulianDay(jd: number): CalendarDate;
329
  toJulianDay(date: AnyCalendarDate): number;
330
  getDaysInMonth(date: AnyCalendarDate): number;
331
  getMonthsInYear(date: AnyCalendarDate): number;
332
  getYearsInEra(date: AnyCalendarDate): number;
333
  getEras(): string[];
334
}
335
```
336

337
## Types
338

339
```typescript { .api }
340
/**
341
 * The Calendar interface represents a calendar system, including information
342
 * about how days, months, years, and eras are organized, and methods to perform
343
 * arithmetic on dates.
344
 */
345
interface Calendar {
346
  /**
347
   * A string identifier for the calendar, as defined by Unicode CLDR.
348
   */
349
  identifier: CalendarIdentifier;
350

351
  /** Creates a CalendarDate in this calendar from the given Julian day number. */
352
  fromJulianDay(jd: number): CalendarDate;
353
  /** Converts a date in this calendar to a Julian day number. */
354
  toJulianDay(date: AnyCalendarDate): number;
355

356
  /** Returns the number of days in the month of the given date. */
357
  getDaysInMonth(date: AnyCalendarDate): number;
358
  /** Returns the number of months in the year of the given date. */
359
  getMonthsInYear(date: AnyCalendarDate): number;
360
  /** Returns the number of years in the era of the given date. */
361
  getYearsInEra(date: AnyCalendarDate): number;
362
  /** Returns a list of era identifiers for the calendar. */
363
  getEras(): string[];
364

365
  /**
366
   * Returns the minimum month number of the given date's year.
367
   * Normally, this is 1, but in some calendars such as the Japanese,
368
   * eras may begin in the middle of a year.
369
   */
370
  getMinimumMonthInYear?(date: AnyCalendarDate): number;
371
  /**
372
   * Returns the minimum day number of the given date's month.
373
   * Normally, this is 1, but in some calendars such as the Japanese,
374
   * eras may begin in the middle of a month.
375
   */
376
  getMinimumDayInMonth?(date: AnyCalendarDate): number;
377

378
  /** Returns whether the given calendar is the same as this calendar. */
379
  isEqual?(calendar: Calendar): boolean;
380
}
381
```