Calendar

The Calendar interface represents a calendar system, including information about how days, months, years, and eras are organized, and methods to perform arithmetic on dates.

Introduction#

While the Gregorian calendar is the most commonly used, many other calendar systems are used throughout the world. The Calendar interface is used to represent calendar systems in the @internationalized/date library. It encapsulates information such as the number of days in a month, the number of months in a year, and the list of eras in a calendar system, as well as methods that handle correct arithmetic of dates in that calendar system, as well as converting dates between calendar systems. Many implementations of this interface are provided in @internationalized/date to handle the most commonly used calendar systems.

As described in the docs for CalendarDate and other date objects, you can pass a Calendar instance to a date to represent a date in that calendar. Date manipulation follows the rules defined by that calendar system. You can also convert between calendar systems using the toCalendar function.

import {
  GregorianCalendar,
  HebrewCalendar,
  toCalendar
} from '@internationalized/date';

let hebrewDate = new CalendarDate(new HebrewCalendar(), 5781, 1, 1);
toCalendar(hebrewDate, new GregorianCalendar());
// => new CalendarDate(new GregorianCalendar(), 2020, 9, 19);

import {
  GregorianCalendar,
  HebrewCalendar,
  toCalendar
} from '@internationalized/date';

let hebrewDate = new CalendarDate(
  new HebrewCalendar(),
  5781,
  1,
  1
);
toCalendar(hebrewDate, new GregorianCalendar());
// => new CalendarDate(new GregorianCalendar(), 2020, 9, 19);

import {
  GregorianCalendar,
  HebrewCalendar,
  toCalendar
} from '@internationalized/date';

let hebrewDate =
  new CalendarDate(
    new HebrewCalendar(),
    5781,
    1,
    1
  );
toCalendar(
  hebrewDate,
  new GregorianCalendar()
);
// => new CalendarDate(new GregorianCalendar(), 2020, 9, 19);

Calendar identifiers#

While it is possible to construct Calendar objects manually, a common usecase is to get a calendar object for a certain locale. Each calendar has an associated string identifier that can be used to retrieve an instance of that calendar using the createCalendar function. A list of supported calendar identifiers is available below.

import {createCalendar} from '@internationalized/date';

createCalendar('gregory');
createCalendar('hebrew');
createCalendar('japanese');

import {createCalendar} from '@internationalized/date';

createCalendar('gregory');
createCalendar('hebrew');
createCalendar('japanese');

import {createCalendar} from '@internationalized/date';

createCalendar(
  'gregory'
);
createCalendar('hebrew');
createCalendar(
  'japanese'
);

Locales are typically represented as strings such as en-US, and represent information about a user's preferences, such as language, script, number format, and calendar. Most of this is automatically determined based on data, but it can also be provided in the locale string itself via a locale extension. For example, the locale "hi-IN-u-ca-indian" represents the Hindi language, in the country of India, using the indian calendar.

The Intl.DateTimeFormat object can be used to get the calendar identifier from a locale string, either provided explicitly or implicitly. This can then be passed to the createCalendar function to retrieve a Calendar instance.

// Get the calendar identifier for the current user.
let calendarIdentifier = new Intl.DateTimeFormat().resolvedOptions().calendar; // e.g. 'gregory'
createCalendar(calendarIdentifier); // new GregorianCalendar()

// Language and region provided, calendar inferred.
let calendarIdentifier =
  new Intl.DateTimeFormat('th-TH').resolvedOptions().calendar; // 'buddhist'
createCalendar(calendarIdentifier); // new BuddhistCalendar()

// Calendar system set explicitly.
let calendarIdentifier =
  new Intl.DateTimeFormat('hi-IN-u-ca-indian').resolvedOptions().calendar; // 'indian'
createCalendar(calendarIdentifier); // new IndianCalendar()

// Get the calendar identifier for the current user.
let calendarIdentifier =
  new Intl.DateTimeFormat().resolvedOptions().calendar; // e.g. 'gregory'
createCalendar(calendarIdentifier); // new GregorianCalendar()

// Language and region provided, calendar inferred.
let calendarIdentifier =
  new Intl.DateTimeFormat('th-TH').resolvedOptions()
    .calendar; // 'buddhist'
createCalendar(calendarIdentifier); // new BuddhistCalendar()

// Calendar system set explicitly.
let calendarIdentifier =
  new Intl.DateTimeFormat('hi-IN-u-ca-indian')
    .resolvedOptions().calendar; // 'indian'
createCalendar(calendarIdentifier); // new IndianCalendar()

// Get the calendar identifier for the current user.
let calendarIdentifier =
  new Intl
    .DateTimeFormat()
    .resolvedOptions()
    .calendar; // e.g. 'gregory'
createCalendar(
  calendarIdentifier
); // new GregorianCalendar()

// Language and region provided, calendar inferred.
let calendarIdentifier =
  new Intl
    .DateTimeFormat(
    'th-TH'
  ).resolvedOptions()
    .calendar; // 'buddhist'
createCalendar(
  calendarIdentifier
); // new BuddhistCalendar()

// Calendar system set explicitly.
let calendarIdentifier =
  new Intl
    .DateTimeFormat(
    'hi-IN-u-ca-indian'
  ).resolvedOptions()
    .calendar; // 'indian'
createCalendar(
  calendarIdentifier
); // new IndianCalendar()

Note: importing createCalendar into your project will result in all available calendars being included in your bundle. If you wish to limit the supported calendars to reduce bundle sizes, you can create your own implementation that only imports the desired classes. This way, your bundler can tree-shake the unused calendar implementations.

import {GregorianCalendar, JapaneseCalendar} from '@internationalized/date';

function createCalendar(identifier) {
  switch (identifier) {
    case 'gregory':
      return new GregorianCalendar();
    case 'japanese':
      return new JapaneseCalendar();
    default:
      throw new Error(`Unsupported calendar ${identifier}`);
  }
}

import {
  GregorianCalendar,
  JapaneseCalendar
} from '@internationalized/date';

function createCalendar(identifier) {
  switch (identifier) {
    case 'gregory':
      return new GregorianCalendar();
    case 'japanese':
      return new JapaneseCalendar();
    default:
      throw new Error(`Unsupported calendar ${identifier}`);
  }
}

import {
  GregorianCalendar,
  JapaneseCalendar
} from '@internationalized/date';

function createCalendar(
  identifier
) {
  switch (identifier) {
    case 'gregory':
      return new GregorianCalendar();
    case 'japanese':
      return new JapaneseCalendar();
    default:
      throw new Error(
        `Unsupported calendar ${identifier}`
      );
  }
}

Implementations#

Interface#

Properties

Methods