CalendarDateTime

A CalendarDateTime represents a date and time without a time zone, in a specific calendar system.

installyarn add @internationalized/date
version3.5.4
usageimport {CalendarDateTime} from '@internationalized/date'

Introduction#


A CalendarDateTime object represents a date and time without a time zone, in a specific calendar system such as the Gregorian calendar. Use this type to represent times that occur at the same local time regardless of the time zone, such as the time of New Years Eve fireworks which always occur at midnight. Most times are better stored as a ZonedDateTime.

A CalendarDateTime can be created using the constructor. This example creates a date that represents February 3rd, 2022 at 9:15 AM in the Gregorian calendar system.

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

let date = new CalendarDateTime(2022, 2, 3, 9, 15);
import {CalendarDateTime} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 3, 9, 15);
import {CalendarDateTime} from '@internationalized/date';

let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    15
  );

You can also create a CalendarDateTime by parsing an ISO 8601 formatted string using the parseDateTime function.

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

let date = parseDateTime('2022-02-03T09:15');
import {parseDateTime} from '@internationalized/date';

let date = parseDateTime('2022-02-03T09:15');
import {parseDateTime} from '@internationalized/date';

let date = parseDateTime(
  '2022-02-03T09:15'
);

Once you have a CalendarDateTime object, you can read its properties, or manipulate it as described in the Manipulating dates section below. You can also convert it to an ISO 8601 string, native JavaScript Date object, or another representation. See the Conversion section below for details.

let date = new CalendarDateTime(2022, 2, 3, 9, 15);
date.toString(); // '2022-02-03T09:15:00'
let date = new CalendarDateTime(2022, 2, 3, 9, 15);
date.toString(); // '2022-02-03T09:15:00'
let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    15
  );
date.toString(); // '2022-02-03T09:15:00'

Interface#


Properties

NameTypeDescription
calendarCalendarThe calendar system associated with this date, e.g. Gregorian.
erastringThe calendar era for this date, e.g. "BC" or "AD".
yearnumberThe year of this date within the era.
monthnumber

The month number within the year. Note that some calendar systems such as Hebrew may have a variable number of months per year. Therefore, month numbers may not always correspond to the same month names in different years.

daynumberThe day number within the month.
hournumberThe hour in the day, numbered from 0 to 23.
minutenumberThe minute in the hour.
secondnumberThe second in the minute.
millisecondnumberThe millisecond in the second.

Methods

MethodDescription
constructor( (...args: any[] )): void
copy(): CalendarDateTimeReturns a copy of this date.
add( (duration: DateTimeDuration )): CalendarDateTimeReturns a new CalendarDateTime with the given duration added to it.
subtract( (duration: DateTimeDuration )): CalendarDateTimeReturns a new CalendarDateTime with the given duration subtracted from it.
set( (fields: DateFieldsTimeFields )): CalendarDateTimeReturns a new CalendarDateTime with the given fields set to the provided values. Other fields will be constrained accordingly.
cycle( field: DateFieldTimeField, amount: number, options?: CycleTimeOptions ): CalendarDateTime

Returns a new CalendarDateTime with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.

toDate( (timeZone: string, , disambiguation?: Disambiguation )): DateConverts the date to a native JavaScript Date object in the given time zone.
toString(): stringConverts the date to an ISO 8601 formatted string.
compare( (b: CalendarDateCalendarDateTimeZonedDateTime )): numberCompares this date with another. A negative result indicates that this date is before the given one, and a positive date indicates that it is after.

Calendar systems#


By default, CalendarDateTime uses the Gregorian calendar system, but many other calendar systems that are used around the world are supported, such as Hebrew, Indian, Islamic, Buddhist, Ethiopic, and more. A Calendar instance can be passed to the CalendarDateTime constructor to represent dates in that calendar system.

This example creates a date in the Buddhist calendar system, which is equivalent to April 4th, 2020 at 9:15 AM in the Gregorian calendar.

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

let date = new CalendarDateTime(new BuddhistCalendar(), 2563, 4, 30, 9, 15);
import {BuddhistCalendar} from '@internationalized/date';

let date = new CalendarDateTime(
  new BuddhistCalendar(),
  2563,
  4,
  30,
  9,
  15
);
import {BuddhistCalendar} from '@internationalized/date';

let date =
  new CalendarDateTime(
    new BuddhistCalendar(),
    2563,
    4,
    30,
    9,
    15
  );

See the Calendar docs for details about the supported calendars.

Eras#

Many calendar systems have only one era, or a modern era and a pre-modern era (e.g. AD and BC in the Gregorian calendar). However, other calendar systems may have many eras. For example, the Japanese calendar has eras for the reign of each Emperor. CalendarDateTime represents eras using string identifiers, which can be passed as an additional parameter to the constructor before the year. When eras are present, years are numbered starting from 1 within the era.

This example creates a date in the Japanese calendar system, which is equivalent to April 4th, 2020 at 9:15 AM in the Gregorian calendar.

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

let date = new CalendarDateTime(
  new JapaneseCalendar(),
  'heisei', 31, 4, 30, 9, 15
);
import {JapaneseCalendar} from '@internationalized/date';

let date = new CalendarDateTime(
  new JapaneseCalendar(),
  'heisei', 31, 4, 30, 9, 15
);
import {JapaneseCalendar} from '@internationalized/date';

let date =
  new CalendarDateTime(
    new JapaneseCalendar(),
    'heisei',
    31,
    4,
    30,
    9,
    15
  );

A list of valid era identifiers can be retrieved using the getEras method of a Calendar instance. If an era is not provided, the date is assumed to be in the current era.

Converting between calendars#

The toCalendar function can be used to convert a date from one calendar system to another.

This example converts a Gregorian date to a Hebrew one.

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

let gregorianDate = new CalendarDateTime(2020, 9, 19, 10, 30);
let hebrewDate = toCalendar(gregorianDate, new HebrewCalendar());
// => new CalendarDateTime(new HebrewCalendar(), 5781, 1, 1, 10, 30)
import {
  HebrewCalendar,
  toCalendar
} from '@internationalized/date';

let gregorianDate = new CalendarDateTime(
  2020,
  9,
  19,
  10,
  30
);
let hebrewDate = toCalendar(
  gregorianDate,
  new HebrewCalendar()
);
// => new CalendarDateTime(new HebrewCalendar(), 5781, 1, 1, 10, 30)
import {
  HebrewCalendar,
  toCalendar
} from '@internationalized/date';

let gregorianDate =
  new CalendarDateTime(
    2020,
    9,
    19,
    10,
    30
  );
let hebrewDate =
  toCalendar(
    gregorianDate,
    new HebrewCalendar()
  );
// => new CalendarDateTime(new HebrewCalendar(), 5781, 1, 1, 10, 30)

Manipulating dates#


Adding and subtracting durations#

A DateTimeDuration is an object that represents an amount of time, with fields such as years, months, hours, and minutes. The add and subtract methods of CalendarDateTime objects can be used to adjust the date by the given duration. These methods return a new date, and do not mutate the original.

let date = new CalendarDateTime(2022, 2, 3, 9, 45);

date.add({weeks: 1}); // 2022-02-10T09:45
date.add({months: 1}); // 2022-03-03T09:45
date.add({years: 1, months: 1, days: 1}); // 2023-03-04T09:45
date.add({hours: 1}); // 2022-02-03T10:45
date.add({minutes: 30}); // 2022-02-03T10:15

date.subtract({weeks: 1}); // 2022-01-27T09:45
date.subtract({months: 1}); // 2022-01-03T09:45
date.subtract({years: 1, months: 1, days: 1}); // 2021-01-02T09:45
date.subtract({hours: 1}); // 2022-02-03T8:45
date.subtract({minutes: 30}); // 2022-02-03T09:15
let date = new CalendarDateTime(2022, 2, 3, 9, 45);

date.add({ weeks: 1 }); // 2022-02-10T09:45
date.add({ months: 1 }); // 2022-03-03T09:45
date.add({ years: 1, months: 1, days: 1 }); // 2023-03-04T09:45
date.add({ hours: 1 }); // 2022-02-03T10:45
date.add({ minutes: 30 }); // 2022-02-03T10:15

date.subtract({ weeks: 1 }); // 2022-01-27T09:45
date.subtract({ months: 1 }); // 2022-01-03T09:45
date.subtract({ years: 1, months: 1, days: 1 }); // 2021-01-02T09:45
date.subtract({ hours: 1 }); // 2022-02-03T8:45
date.subtract({ minutes: 30 }); // 2022-02-03T09:15
let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );

date.add({ weeks: 1 }); // 2022-02-10T09:45
date.add({ months: 1 }); // 2022-03-03T09:45
date.add({
  years: 1,
  months: 1,
  days: 1
}); // 2023-03-04T09:45
date.add({ hours: 1 }); // 2022-02-03T10:45
date.add({
  minutes: 30
}); // 2022-02-03T10:15

date.subtract({
  weeks: 1
}); // 2022-01-27T09:45
date.subtract({
  months: 1
}); // 2022-01-03T09:45
date.subtract({
  years: 1,
  months: 1,
  days: 1
}); // 2021-01-02T09:45
date.subtract({
  hours: 1
}); // 2022-02-03T8:45
date.subtract({
  minutes: 30
}); // 2022-02-03T09:15

Adding or subtracting a duration that goes beyond the limits of a particular field will cause the date to be balanced. For example, adding one day to August 31st results in September 1st. In addition, if adding or subtracting one field causes another to be invalid, the date will be constrained. For example, adding one month to August 31st results in September 30th because September 31st does not exist.

Parsing durations#

The parseDuration function can be used to convert a ISO 8601 duration string into a DateTimeDuration object. The smallest time unit may include decimal values written with a comma or period, and negative values can be written by prefixing the entire string with a minus sign.

parseDuration('P3Y6M6W4DT12H30M5S');
// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5}

parseDuration('-P3Y6M6W4DT12H30M5S');
// => {years: -3, months: -6, weeks: -6, days: -4, hours: -12, minutes: -30, seconds: -5}

parseDuration('P3Y6M6W4DT12H30M5.5S');
// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5.5}
parseDuration('P3Y6M6W4DT12H30M5S');
// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5}

parseDuration('-P3Y6M6W4DT12H30M5S');
// => {years: -3, months: -6, weeks: -6, days: -4, hours: -12, minutes: -30, seconds: -5}

parseDuration('P3Y6M6W4DT12H30M5.5S');
// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5.5}
parseDuration(
  'P3Y6M6W4DT12H30M5S'
);
// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5}

parseDuration(
  '-P3Y6M6W4DT12H30M5S'
);
// => {years: -3, months: -6, weeks: -6, days: -4, hours: -12, minutes: -30, seconds: -5}

parseDuration(
  'P3Y6M6W4DT12H30M5.5S'
);
// => {years: 3, months: 6, weeks: 6, days: 4, hours: 12, minutes: 30, seconds: 5.5}

Setting fields#

CalendarDateTime objects are immutable, which means their properties cannot be set directly. Instead, use the set method, and pass the fields to be modified. This will return a new CalendarDateTime with the updated values.

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
date.set({day: 10}); // 2022-02-10T09:45
date.set({month: 5}); // 2022-05-03T09:45
date.set({year: 2023, month: 10, day: 16}); // 2023-10-16T09:45
date.set({hour: 18}); // 2022-02-03T18:45
date.set({minute: 15}); // 2022-02-03T09:15
let date = new CalendarDateTime(2022, 2, 3, 9, 45);
date.set({ day: 10 }); // 2022-02-10T09:45
date.set({ month: 5 }); // 2022-05-03T09:45
date.set({ year: 2023, month: 10, day: 16 }); // 2023-10-16T09:45
date.set({ hour: 18 }); // 2022-02-03T18:45
date.set({ minute: 15 }); // 2022-02-03T09:15
let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );
date.set({ day: 10 }); // 2022-02-10T09:45
date.set({ month: 5 }); // 2022-05-03T09:45
date.set({
  year: 2023,
  month: 10,
  day: 16
}); // 2023-10-16T09:45
date.set({ hour: 18 }); // 2022-02-03T18:45
date.set({ minute: 15 }); // 2022-02-03T09:15

Setting a field to a value that is outside the valid range will cause it to be constrained. For example, setting the day to a value that is greater than the number of days in the month, will result in the last day of the month.

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
date.set({day: 100}); // 2022-02-28T09:45
date.set({month: 20}); // 2022-12-03T09:45
date.set({hour: 30}); // 2022-02-03T23:45
let date = new CalendarDateTime(2022, 2, 3, 9, 45);
date.set({day: 100}); // 2022-02-28T09:45
date.set({month: 20}); // 2022-12-03T09:45
date.set({hour: 30}); // 2022-02-03T23:45
let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );
date.set({ day: 100 }); // 2022-02-28T09:45
date.set({ month: 20 }); // 2022-12-03T09:45
date.set({ hour: 30 }); // 2022-02-03T23:45

Cycling fields#

The cycle method allows incrementing or decrementing a single field. It is similar to the add and subtract methods, but when the value reaches the minimum or maximum, it wraps around rather than affecting other fields.

let date = new CalendarDateTime(2022, 12, 31, 23, 59);
date.cycle('day', 1); // 2022-12-01T23:59
date.cycle('month', 1); // 2022-01-31T23:59
date.cycle('hour', 1); // 2022-12-31T00:59
date.cycle('minute', 1); // 2022-12-31T23:00

let date = new CalendarDateTime(2022, 1, 1, 0, 0);
date.cycle('day', -1); // 2022-01-31T00:00
date.cycle('month', -1); // 2022-12-01T00:00
date.cycle('hour', -1); // 2022-01-01T23:00
date.cycle('minute', -1); // 2022-01-01T00:59
let date = new CalendarDateTime(2022, 12, 31, 23, 59);
date.cycle('day', 1); // 2022-12-01T23:59
date.cycle('month', 1); // 2022-01-31T23:59
date.cycle('hour', 1); // 2022-12-31T00:59
date.cycle('minute', 1); // 2022-12-31T23:00

let date = new CalendarDateTime(2022, 1, 1, 0, 0);
date.cycle('day', -1); // 2022-01-31T00:00
date.cycle('month', -1); // 2022-12-01T00:00
date.cycle('hour', -1); // 2022-01-01T23:00
date.cycle('minute', -1); // 2022-01-01T00:59
let date =
  new CalendarDateTime(
    2022,
    12,
    31,
    23,
    59
  );
date.cycle('day', 1); // 2022-12-01T23:59
date.cycle('month', 1); // 2022-01-31T23:59
date.cycle('hour', 1); // 2022-12-31T00:59
date.cycle('minute', 1); // 2022-12-31T23:00

let date =
  new CalendarDateTime(
    2022,
    1,
    1,
    0,
    0
  );
date.cycle('day', -1); // 2022-01-31T00:00
date.cycle('month', -1); // 2022-12-01T00:00
date.cycle('hour', -1); // 2022-01-01T23:00
date.cycle('minute', -1); // 2022-01-01T00:59

Note that if cycling a field causes another field to become invalid, the date is constrained. For example, adding one month to August 31st results in September 30th because September 31st does not exist.

The round option may also be passed, which causes the value to be rounded to increments of the given amount. For example, you could round the minute to increments of 15.

let date = new CalendarDateTime(2022, 2, 3, 9, 22);

date.cycle('minute', 15); // 2027-02-03T09:37
date.cycle('minute', 15, {round: true}); // 2025-02-03T09:30

date.cycle('minute', -15); // 2017-02-03T09:07
date.cycle('minute', -15, {round: true}); // 2020-02-03T09:15
let date = new CalendarDateTime(2022, 2, 3, 9, 22);

date.cycle('minute', 15); // 2027-02-03T09:37
date.cycle('minute', 15, { round: true }); // 2025-02-03T09:30

date.cycle('minute', -15); // 2017-02-03T09:07
date.cycle('minute', -15, { round: true }); // 2020-02-03T09:15
let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    22
  );

date.cycle('minute', 15); // 2027-02-03T09:37
date.cycle(
  'minute',
  15,
  { round: true }
); // 2025-02-03T09:30

date.cycle(
  'minute',
  -15
); // 2017-02-03T09:07
date.cycle(
  'minute',
  -15,
  { round: true }
); // 2020-02-03T09:15

By default, the hour field is cycled within a 24 hour range. The hourCycle option can be set to 12 to use a 12 hour clock instead, which will preserve the AM/PM value when formatted.

let date = new CalendarDateTime(2022, 2, 3, 11);
date.cycle('hour', 1); // 2022-02-03T12:00
date.cycle('hour', 1, {hourCycle: 12}); // 2022-02-03T00:00

let date = new CalendarDateTime(2022, 2, 3, 23);
date.cycle('hour', 1); // 2022-02-03T00:00
date.cycle('hour', 1, {hourCycle: 12}); // 2022-02-03T12:00
let date = new CalendarDateTime(2022, 2, 3, 11);
date.cycle('hour', 1); // 2022-02-03T12:00
date.cycle('hour', 1, {hourCycle: 12}); // 2022-02-03T00:00

let date = new CalendarDateTime(2022, 2, 3, 23);
date.cycle('hour', 1); // 2022-02-03T00:00
date.cycle('hour', 1, {hourCycle: 12}); // 2022-02-03T12:00
let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    11
  );
date.cycle('hour', 1); // 2022-02-03T12:00
date.cycle('hour', 1, {
  hourCycle: 12
}); // 2022-02-03T00:00

let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    23
  );
date.cycle('hour', 1); // 2022-02-03T00:00
date.cycle('hour', 1, {
  hourCycle: 12
}); // 2022-02-03T12:00

Conversion#


To a string#

CalendarDateTime objects can be converted to an ISO 8601 formatted string using the toString method.

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
date.toString(); // '2022-02-03T09:45:00'
let date = new CalendarDateTime(2022, 2, 3, 9, 45);
date.toString(); // '2022-02-03T09:45:00'
let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );
date.toString(); // '2022-02-03T09:45:00'

To a date or time only#

A CalendarDateTime can be converted to a CalendarDate or Time object if only one of these components is needed.

Use the toCalendarDate function to convert a CalendarDateTime to a CalendarDate.

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

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
toCalendarDate(date); // 2022-02-03
import {toCalendarDate} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
toCalendarDate(date); // 2022-02-03
import {toCalendarDate} from '@internationalized/date';

let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );
toCalendarDate(date); // 2022-02-03

Use the toTime function to convert a CalendarDateTime to a Time.

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

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
toTime(date); // 09:45:00
import {toTime} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
toTime(date); // 09:45:00
import {toTime} from '@internationalized/date';

let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );
toTime(date); // 09:45:00

To a ZonedDateTime#

A CalendarDateTime can be converted to a local time in a specific time zone using the toZoned function. This returns a ZonedDateTime object, which represents an exact moment in time at a particular location on Earth.

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

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
toZoned(date, 'America/Los_Angeles'); // 2022-02-03T09:45-07:00[America/Los_Angeles]
import {toZoned} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
toZoned(date, 'America/Los_Angeles'); // 2022-02-03T09:45-07:00[America/Los_Angeles]
import {toZoned} from '@internationalized/date';

let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );
toZoned(
  date,
  'America/Los_Angeles'
); // 2022-02-03T09:45-07:00[America/Los_Angeles]

Some time values during daylight saving transitions may be ambiguous. For example, in the United States, the 2 AM hour is skipped in the spring, and the 1 AM hour occurs twice in the fall. When converting a CalendarDateTime to a ZonedDateTime, this ambiguity must be resolved to determine the exact time. By default, the later of the two possible times is chosen for "spring forward" transitions, and the earlier time is chosen for "fall back" transitions. This can be controlled by passing the disambiguation parameter to the toZoned function.

  • 'earlier' – choose the earlier of the two possible times
  • 'later' – choose the later of the two possible times
  • 'compatible' (default) – choose the later of the two times during "spring forward" transitions, and the earlier time during "fall back" transitions.
  • 'reject' – throws an error when the time is ambiguous
// A "spring forward" transition
let date = new CalendarDateTime(2020, 3, 8, 2);
toZoned(date, 'America/Los_Angeles'); // 2020-03-08T03:00:00-07:00[America/Los_Angeles]
toZoned(date, 'America/Los_Angeles', 'earlier'); // 2020-03-08T01:00:00-08:00[America/Los_Angeles]
toZoned(date, 'America/Los_Angeles', 'later'); // 2020-03-08T03:00:00-07:00[America/Los_Angeles]

// A "fall back" transition
let date = new CalendarDateTime(2020, 11, 1, 1);
toZoned(date, 'America/Los_Angeles'); // 2020-11-01T01:00:00-07:00[America/Los_Angeles]
toZoned(date, 'America/Los_Angeles', 'earlier'); // 2020-11-01T01:00:00-07:00[America/Los_Angeles]
toZoned(date, 'America/Los_Angeles', 'later'); // 2020-11-01T01:00:00-08:00[America/Los_Angeles]
// A "spring forward" transition
let date = new CalendarDateTime(2020, 3, 8, 2);
toZoned(date, 'America/Los_Angeles'); // 2020-03-08T03:00:00-07:00[America/Los_Angeles]
toZoned(date, 'America/Los_Angeles', 'earlier'); // 2020-03-08T01:00:00-08:00[America/Los_Angeles]
toZoned(date, 'America/Los_Angeles', 'later'); // 2020-03-08T03:00:00-07:00[America/Los_Angeles]

// A "fall back" transition
let date = new CalendarDateTime(2020, 11, 1, 1);
toZoned(date, 'America/Los_Angeles'); // 2020-11-01T01:00:00-07:00[America/Los_Angeles]
toZoned(date, 'America/Los_Angeles', 'earlier'); // 2020-11-01T01:00:00-07:00[America/Los_Angeles]
toZoned(date, 'America/Los_Angeles', 'later'); // 2020-11-01T01:00:00-08:00[America/Los_Angeles]
// A "spring forward" transition
let date =
  new CalendarDateTime(
    2020,
    3,
    8,
    2
  );
toZoned(
  date,
  'America/Los_Angeles'
); // 2020-03-08T03:00:00-07:00[America/Los_Angeles]
toZoned(
  date,
  'America/Los_Angeles',
  'earlier'
); // 2020-03-08T01:00:00-08:00[America/Los_Angeles]
toZoned(
  date,
  'America/Los_Angeles',
  'later'
); // 2020-03-08T03:00:00-07:00[America/Los_Angeles]

// A "fall back" transition
let date =
  new CalendarDateTime(
    2020,
    11,
    1,
    1
  );
toZoned(
  date,
  'America/Los_Angeles'
); // 2020-11-01T01:00:00-07:00[America/Los_Angeles]
toZoned(
  date,
  'America/Los_Angeles',
  'earlier'
); // 2020-11-01T01:00:00-07:00[America/Los_Angeles]
toZoned(
  date,
  'America/Los_Angeles',
  'later'
); // 2020-11-01T01:00:00-08:00[America/Los_Angeles]

To a native Date object#

A CalendarDateTime can be converted to a native JavaScript Date object using the toDate method. In general, the Date object should be avoided because it has many internationalization issues and other flaws. However, it is necessary to use some functionality like date formatting.

Because a Date represents an exact time, a time zone identifier is required to be passed to the toDate method. The getLocalTimeZone function can be used to retrieve the user's current time zone.

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

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
date.toDate('America/Los_Angeles'); // Thu Feb 03 2022 09:45:00 GMT-0800 (Pacific Standard Time)
date.toDate(getLocalTimeZone()); // e.g. Thu Feb 03 2022 09:45:00 GMT-0500 (Eastern Standard Time)
import {getLocalTimeZone} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 3, 9, 45);
date.toDate('America/Los_Angeles'); // Thu Feb 03 2022 09:45:00 GMT-0800 (Pacific Standard Time)
date.toDate(getLocalTimeZone()); // e.g. Thu Feb 03 2022 09:45:00 GMT-0500 (Eastern Standard Time)
import {getLocalTimeZone} from '@internationalized/date';

let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );
date.toDate(
  'America/Los_Angeles'
); // Thu Feb 03 2022 09:45:00 GMT-0800 (Pacific Standard Time)
date.toDate(
  getLocalTimeZone()
); // e.g. Thu Feb 03 2022 09:45:00 GMT-0500 (Eastern Standard Time)

Some time values during daylight saving transitions may be ambiguous. For example, in the United States, the 2 AM hour is skipped in the spring, and the 1 AM hour occurs twice in the fall. When converting a CalendarDateTime to a Date, this ambiguity must be resolved to determine the exact time. This behavior can be controlled using the disambiguation parameter, as described above.

// A "spring forward" transition
let date = new CalendarDateTime(2020, 3, 8, 2);
date.toDate('America/Los_Angeles', 'earlier');
// => Sun Mar 08 2020 01:00:00 GMT-0800 (Pacific Daylight Time)
// A "spring forward" transition
let date = new CalendarDateTime(2020, 3, 8, 2);
date.toDate('America/Los_Angeles', 'earlier');
// => Sun Mar 08 2020 01:00:00 GMT-0800 (Pacific Daylight Time)
// A "spring forward" transition
let date =
  new CalendarDateTime(
    2020,
    3,
    8,
    2
  );
date.toDate(
  'America/Los_Angeles',
  'earlier'
);
// => Sun Mar 08 2020 01:00:00 GMT-0800 (Pacific Daylight Time)

Queries#


Comparison#

CalendarDateTime objects can be compared either for full or partial equality, or in order to determine which date is before or after another.

The compare method can be used to determine if a date is before or after another. It returns a number less than zero if the first date is before the second, zero if the values are equal, or a number greater than zero if the first date is after the second.

let a = new CalendarDateTime(2022, 2, 3, 9, 45);
let b = new CalendarDateTime(2022, 3, 4, 12, 20);

a.compare(b) < 0; // true
b.compare(a) > 0; // true
let a = new CalendarDateTime(2022, 2, 3, 9, 45);
let b = new CalendarDateTime(2022, 3, 4, 12, 20);

a.compare(b) < 0; // true
b.compare(a) > 0; // true
let a =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );
let b =
  new CalendarDateTime(
    2022,
    3,
    4,
    12,
    20
  );

a.compare(b) < 0; // true
b.compare(a) > 0; // true

In addition, the following functions can be used to perform a partial comparison. These functions accept dates in different calendar systems, and the second date is converted to the calendar system of the first date before comparison.

  • isSameYearReturns whether the given dates occur in the same year, using the calendar system of the first date.
  • isSameMonthReturns whether the given dates occur in the same month, using the calendar system of the first date.
  • isSameDayReturns whether the given dates occur on the same day, regardless of the time or calendar system.
  • isTodayReturns whether the date is today in the given time zone.
import {IslamicUmalquraCalendar, isSameMonth} from '@internationalized/date';

isSameMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(2021, 4, 30, 5, 15)
); // true
isSameMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(2021, 8, 2, 5, 15)
); // false
isSameMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(new IslamicUmalquraCalendar(), 1442, 9, 4, 5, 15)
); // true
import {
  IslamicUmalquraCalendar,
  isSameMonth
} from '@internationalized/date';

isSameMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(2021, 4, 30, 5, 15)
); // true
isSameMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(2021, 8, 2, 5, 15)
); // false
isSameMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(
    new IslamicUmalquraCalendar(),
    1442,
    9,
    4,
    5,
    15
  )
); // true
import {
  IslamicUmalquraCalendar,
  isSameMonth
} from '@internationalized/date';

isSameMonth(
  new CalendarDateTime(
    2021,
    4,
    16,
    9,
    45
  ),
  new CalendarDateTime(
    2021,
    4,
    30,
    5,
    15
  )
); // true
isSameMonth(
  new CalendarDateTime(
    2021,
    4,
    16,
    9,
    45
  ),
  new CalendarDateTime(
    2021,
    8,
    2,
    5,
    15
  )
); // false
isSameMonth(
  new CalendarDateTime(
    2021,
    4,
    16,
    9,
    45
  ),
  new CalendarDateTime(
    new IslamicUmalquraCalendar(),
    1442,
    9,
    4,
    5,
    15
  )
); // true

A similar set of functions is also available that does not convert between calendar systems and requires the calendars to be equal.

  • isEqualYearReturns whether the given dates occur in the same year, and are of the same calendar system.
  • isEqualMonthReturns whether the given dates occur in the same month, and are of the same calendar system.
  • isEqualDayReturns whether the given dates occur on the same day, and are of the same calendar system.
import {isEqualMonth, IslamicUmalquraCalendar} from '@internationalized/date';

isEqualMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(2021, 4, 30, 5, 15)
); // true
isEqualMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(2021, 8, 2, 5, 15)
); // false
isEqualMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(new IslamicUmalquraCalendar(), 1442, 9, 4, 5, 15)
); // false
import {
  isEqualMonth,
  IslamicUmalquraCalendar
} from '@internationalized/date';

isEqualMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(2021, 4, 30, 5, 15)
); // true
isEqualMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(2021, 8, 2, 5, 15)
); // false
isEqualMonth(
  new CalendarDateTime(2021, 4, 16, 9, 45),
  new CalendarDateTime(
    new IslamicUmalquraCalendar(),
    1442,
    9,
    4,
    5,
    15
  )
); // false
import {
  isEqualMonth,
  IslamicUmalquraCalendar
} from '@internationalized/date';

isEqualMonth(
  new CalendarDateTime(
    2021,
    4,
    16,
    9,
    45
  ),
  new CalendarDateTime(
    2021,
    4,
    30,
    5,
    15
  )
); // true
isEqualMonth(
  new CalendarDateTime(
    2021,
    4,
    16,
    9,
    45
  ),
  new CalendarDateTime(
    2021,
    8,
    2,
    5,
    15
  )
); // false
isEqualMonth(
  new CalendarDateTime(
    2021,
    4,
    16,
    9,
    45
  ),
  new CalendarDateTime(
    new IslamicUmalquraCalendar(),
    1442,
    9,
    4,
    5,
    15
  )
); // false

Start and end dates#

The following functions can be used to find the start or end dates of a particular unit of time. These only affect the date components of a CalendarDateTime. The time fields are left unchanged.

  • startOfYearReturns the first day of the year for the given date.
  • endOfYearReturns the last day of the year for the given date.
  • startOfMonthReturns the first date of the month for the given date.
  • endOfMonthReturns the last date of the month for the given date.
  • startOfWeekReturns the first date of the week for the given date and locale.
  • endOfWeekReturns the last date of the week for the given date and locale.

Note that startOfWeek and endOfWeek require a locale string to be provided. This is because the first day of the week changes depending on the locale. For example, in the United States, the first day of the week is on Sunday, but in France it is on Monday.

import {startOfYear, startOfMonth, startOfWeek} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 3, 9, 45);

startOfYear(date); // 2022-01-01T09:45
startOfMonth(date); // 2022-02-01T09:45
startOfWeek(date, 'en-US'); // 2022-01-30T09:45
startOfWeek(date, 'fr-FR'); // 2022-01-31T09:45
import {
  startOfMonth,
  startOfWeek,
  startOfYear
} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 3, 9, 45);

startOfYear(date); // 2022-01-01T09:45
startOfMonth(date); // 2022-02-01T09:45
startOfWeek(date, 'en-US'); // 2022-01-30T09:45
startOfWeek(date, 'fr-FR'); // 2022-01-31T09:45
import {
  startOfMonth,
  startOfWeek,
  startOfYear
} from '@internationalized/date';

let date =
  new CalendarDateTime(
    2022,
    2,
    3,
    9,
    45
  );

startOfYear(date); // 2022-01-01T09:45
startOfMonth(date); // 2022-02-01T09:45
startOfWeek(
  date,
  'en-US'
); // 2022-01-30T09:45
startOfWeek(
  date,
  'fr-FR'
); // 2022-01-31T09:45

Day of week#

The getDayOfWeek function returns the day of the week for the given date and locale. Days are numbered from zero to six, where zero is the first day of the week in the given locale. For example, in the United States, the first day of the week is Sunday, but in France it is Monday.

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

let date = new CalendarDateTime(2022, 2, 6, 8, 30); // a Sunday

getDayOfWeek(date, 'en-US'); // 0
getDayOfWeek(date, 'fr-FR'); // 6
import {getDayOfWeek} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 6, 8, 30); // a Sunday

getDayOfWeek(date, 'en-US'); // 0
getDayOfWeek(date, 'fr-FR'); // 6
import {getDayOfWeek} from '@internationalized/date';

let date =
  new CalendarDateTime(
    2022,
    2,
    6,
    8,
    30
  ); // a Sunday

getDayOfWeek(
  date,
  'en-US'
); // 0
getDayOfWeek(
  date,
  'fr-FR'
); // 6

Weekdays and weekends#

The isWeekday and isWeekend functions can be used to determine if a date is weekday or weekend respectively. This depends on the locale. For example, in the United States, weekends are Saturday and Sunday, but in Israel they are Friday and Saturday.

import {isWeekday, isWeekend} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 6, 8, 30); // a Sunday

isWeekday(date, 'en-US'); // false
isWeekday(date, 'he-IL'); // true

isWeekend(date, 'en-US'); // true
isWeekend(date, 'he-IL'); // false
import {
  isWeekday,
  isWeekend
} from '@internationalized/date';

let date = new CalendarDateTime(2022, 2, 6, 8, 30); // a Sunday

isWeekday(date, 'en-US'); // false
isWeekday(date, 'he-IL'); // true

isWeekend(date, 'en-US'); // true
isWeekend(date, 'he-IL'); // false
import {
  isWeekday,
  isWeekend
} from '@internationalized/date';

let date =
  new CalendarDateTime(
    2022,
    2,
    6,
    8,
    30
  ); // a Sunday

isWeekday(date, 'en-US'); // false
isWeekday(date, 'he-IL'); // true

isWeekend(date, 'en-US'); // true
isWeekend(date, 'he-IL'); // false

Weeks in month#

The getWeeksInMonth function returns the number of weeks in the given month. This depends on the number of days in the month, what day of the week the month starts on, and the given locale. For example, in the United States, the first day of the week is Sunday, but in France it is Monday.

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

let date = new CalendarDateTime(2021, 1, 1, 8, 30);

getWeeksInMonth(date, 'en-US'); // 6
getWeeksInMonth(date, 'fr-FR'); // 5
import {getWeeksInMonth} from '@internationalized/date';

let date = new CalendarDateTime(2021, 1, 1, 8, 30);

getWeeksInMonth(date, 'en-US'); // 6
getWeeksInMonth(date, 'fr-FR'); // 5
import {getWeeksInMonth} from '@internationalized/date';

let date =
  new CalendarDateTime(
    2021,
    1,
    1,
    8,
    30
  );

getWeeksInMonth(
  date,
  'en-US'
); // 6
getWeeksInMonth(
  date,
  'fr-FR'
); // 5