alpha

Time

A Time represents a clock time without any date components.

install	`yarn add @internationalized/date`
version	3.0.0-alpha.4
usage	`import {Time} from '@internationalized/date'`

View repository

GitHub

View package

NPM

Introduction#

A Time object represents a clock time without any date components. If you need to refer to a time on a specific date, use a CalendarDateTime or ZonedDateTime instead.

A Time can be created using the constructor. This example creates a time that represents 9:45 AM.

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

let time = new Time(9, 45);

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

let time = new Time(9, 45);

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

let time = new Time(
  9,
  45
);

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

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

let time = parseTime('09:45');

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

let time = parseTime('09:45');

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

let time = parseTime(
  '09:45'
);

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

let time = new Time(9, 45);
time.toString(); // '09:45:00'

let time = new Time(9, 45);
time.toString(); // '09:45:00'

let time = new Time(
  9,
  45
);
time.toString(); // '09:45:00'

Interface#

Properties

Name	Type	Description
`hour`	`number`	The hour, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.

Methods

Method	Description
`constructor( hour: number, minute: number, second: number, millisecond: number ): void`
`copy(): Time`	Returns a copy of this time.
`add( (duration: TimeDuration )): void`	Returns a new `Time` with the given duration added to it.
`subtract( (duration: TimeDuration )): void`	Returns a new `Time` with the given duration subtracted from it.
`set( (fields: TimeFields )): void`	Returns a new `Time` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: TimeField, amount: number, options?: CycleTimeOptions ): void`	Returns a new `Time` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toString(): void`	Converts the time to an ISO 8601 formatted string.
`compare( (b: AnyTime )): void`	Compares this time with another. A negative result indicates that this time is before the given one, and a positive time indicates that it is after.

Manipulating times#

Adding and subtracting durations#

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

let time = new Time(9, 45);
time.add({hours: 1}); // 10:45:00
time.add({minutes: 1}); // 09:46:00
time.add({seconds: 1}); // 09:45:01

let time = new Time(9, 45);
time.add({hours: 1}); // 10:45:00
time.add({minutes: 1}); // 09:46:00
time.add({seconds: 1}); // 09:45:01

let time = new Time(
  9,
  45
);
time.add({ hours: 1 }); // 10:45:00
time.add({ minutes: 1 }); // 09:46:00
time.add({ seconds: 1 }); // 09:45:01

Adding or subtracting a duration that goes beyond the limits of a particular field will cause the time to be balanced. For example, adding one minute to 09:59 results in 10:00.

Setting fields#

Time 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 Time with the updated values.

let time = new Time(9, 45);
time.set({hour: 12}); // 12:45
time.set({minute: 5}); // 9:05

let time = new Time(9, 45);
time.set({hour: 12}); // 12:45
time.set({minute: 5}); // 9:05

let time = new Time(
  9,
  45
);
time.set({ hour: 12 }); // 12:45
time.set({ minute: 5 }); // 9:05

Setting a field to a value that is outside the valid range will cause it to be constrained.

let time = new Time(9, 45);
time.set({hour: 36}); // 23:45
time.set({minute: 75}); // 09:59

let time = new Time(9, 45);
time.set({hour: 36}); // 23:45
time.set({minute: 75}); // 09:59

let time = new Time(
  9,
  45
);
time.set({ hour: 36 }); // 23:45
time.set({ minute: 75 }); // 09:59

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 time = new Time(23, 59);
date.cycle('hour', 1); // 00:59
date.cycle('minute', 1); // 23:00

let time = new Time(0, 0);
date.cycle('hour', -1); // 23:00
date.cycle('minute', -1); // 00:59

let time = new Time(23, 59);
date.cycle('hour', 1); // 00:59
date.cycle('minute', 1); // 23:00

let time = new Time(0, 0);
date.cycle('hour', -1); // 23:00
date.cycle('minute', -1); // 00:59

let time = new Time(
  23,
  59
);
date.cycle('hour', 1); // 00:59
date.cycle('minute', 1); // 23:00

let time = new Time(
  0,
  0
);
date.cycle('hour', -1); // 23:00
date.cycle('minute', -1); // 00:59

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 time = new Time(9, 22);

time.cycle('minute', 15); // 09:37
time.cycle('minute', 15, {round: true}); // 09:30

time.cycle('minute', -15); // 09:07
time.cycle('minute', -15, {round: true}); // 09:15

let time = new Time(9, 22);

time.cycle('minute', 15); // 09:37
time.cycle('minute', 15, {round: true}); // 09:30

time.cycle('minute', -15); // 09:07
time.cycle('minute', -15, {round: true}); // 09:15

let time = new Time(
  9,
  22
);

time.cycle('minute', 15); // 09:37
time.cycle(
  'minute',
  15,
  { round: true }
); // 09:30

time.cycle(
  'minute',
  -15
); // 09:07
time.cycle(
  'minute',
  -15,
  { round: true }
); // 09: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 time = new Time(11);
time.cycle('hour', 1); // 12:00
time.cycle('hour', 1, {hourCycle: 12}); // 00:00

let time = new Time(23);
time.cycle('hour', 1); // 00:00
time.cycle('hour', 1, {hourCycle: 12}); // 12:00

let time = new Time(11);
time.cycle('hour', 1); // 12:00
time.cycle('hour', 1, {hourCycle: 12}); // 00:00

let time = new Time(23);
time.cycle('hour', 1); // 00:00
time.cycle('hour', 1, {hourCycle: 12}); // 12:00

let time = new Time(11);
time.cycle('hour', 1); // 12:00
time.cycle('hour', 1, {
  hourCycle: 12
}); // 00:00

let time = new Time(23);
time.cycle('hour', 1); // 00:00
time.cycle('hour', 1, {
  hourCycle: 12
}); // 12:00

Conversion#

To a string#

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

let date = new Time(9, 45);
date.toString(); // '09:45:00'

let date = new Time(9, 45);
date.toString(); // '09:45:00'

let date = new Time(
  9,
  45
);
date.toString(); // '09:45:00'

To a date and time#

A Time can be combined with a CalendarDate to produce a CalendarDateTime object using the toCalendarDateTime function.

import {toCalendarDateTime, CalendarDate} from '@internationalized/date';

let date = new CalendarDate(2022, 2, 3);
let time = new Time(8, 30);

toCalendarDateTime(date, time); // 2022-02-03T08:30:00

import {
  CalendarDate,
  toCalendarDateTime
} from '@internationalized/date';

let date = new CalendarDate(2022, 2, 3);
let time = new Time(8, 30);

toCalendarDateTime(date, time); // 2022-02-03T08:30:00

import {
  CalendarDate,
  toCalendarDateTime
} from '@internationalized/date';

let date =
  new CalendarDate(
    2022,
    2,
    3
  );
let time = new Time(
  8,
  30
);

toCalendarDateTime(
  date,
  time
); // 2022-02-03T08:30:00

A CalendarDateTime represents a date with a time, but not in any specific time zone. 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, which represents a date with a time in a specific time zone. Use this type to represent an exact moment in time at a particular location on Earth.

The toZoned function can be used to convert a CalendarDateTime to a ZonedDateTime.

import {
  CalendarDate,
  toCalendarDateTime,
  toZoned
} from '@internationalized/date';

let date = new CalendarDate(2022, 2, 3);
let time = new Time(8, 30);

let dateTime = toCalendarDateTime(date, time); // 2022-02-03T08:30:00
toZoned(dateTime, 'America/Los_Angeles'); // 2021-02-03T08:30-07:00[America/Los_Angeles]

import {
  CalendarDate,
  toCalendarDateTime,
  toZoned
} from '@internationalized/date';

let date = new CalendarDate(2022, 2, 3);
let time = new Time(8, 30);

let dateTime = toCalendarDateTime(date, time); // 2022-02-03T08:30:00
toZoned(dateTime, 'America/Los_Angeles'); // 2021-02-03T08:30-07:00[America/Los_Angeles]

import {
  CalendarDate,
  toCalendarDateTime,
  toZoned
} from '@internationalized/date';

let date =
  new CalendarDate(
    2022,
    2,
    3
  );
let time = new Time(
  8,
  30
);

let dateTime =
  toCalendarDateTime(
    date,
    time
  ); // 2022-02-03T08:30:00
toZoned(
  dateTime,
  'America/Los_Angeles'
); // 2021-02-03T08:30-07:00[America/Los_Angeles]

Queries#

Comparison#

Time objects can be compared in order to determine which time is before or after another using the compare method. It returns a number less than zero if the first time is before the second, zero if the values are equal, or a number greater than zero if the first time is after the second.

let a = new Time(9, 45);
let b = new Time(12, 20);

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

let a = new Time(9, 45);
let b = new Time(12, 20);

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

let a = new Time(9, 45);
let b = new Time(12, 20);

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

parseTime(
  (value: string
)): Time

A Time represents a clock time without any date components.

Properties

Name	Type	Description
`hour`	`number`	The hour, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.

Methods

Method	Description
`constructor( hour: number, minute: number, second: number, millisecond: number ): void`
`copy(): Time`	Returns a copy of this time.
`add( (duration: TimeDuration )): void`	Returns a new `Time` with the given duration added to it.
`subtract( (duration: TimeDuration )): void`	Returns a new `Time` with the given duration subtracted from it.
`set( (fields: TimeFields )): void`	Returns a new `Time` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: TimeField, amount: number, options?: CycleTimeOptions ): void`	Returns a new `Time` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toString(): void`	Converts the time to an ISO 8601 formatted string.
`compare( (b: AnyTime )): void`	Compares this time with another. A negative result indicates that this time is before the given one, and a positive time indicates that it is after.

Represents an amount of time, for use whe performing arithmetic.

Name	Type	Description
`hours`	`number`	The number of hours to add or subtract.
`minutes`	`number`	The number of minutes to add or subtract.
`seconds`	`number`	The number of seconds to add or subtract.
`milliseconds`	`number`	The number of milliseconds to add or subtract.

Name	Type	Description
`hour`	`number`
`minute`	`number`
`second`	`number`
`millisecond`	`number`

Name	Type	Default	Description
`hourCycle`	`12 \| 24`	`24`	Whether to use 12 or 24 hour time. If 12 hour time is chosen, the resulting value will remain in the same day period as the original value (e.g. if the value is AM, the resulting value also be AM).
`round`	`boolean`	—	Whether to round the field value to the nearest interval of the amount.

Name	Type	Description
`hour`	`number`
`minute`	`number`
`second`	`number`
`millisecond`	`number`

Method	Description
`copy():`

Converts a date value to a CalendarDateTime. An optional Time value can be passed to set the time of the resulting value, otherwise it will default to midnight.

toCalendarDateTime(
  (date: CalendarDate
  | CalendarDateTime
  | ZonedDateTime,
  , time?: AnyTime
)): CalendarDateTime

A CalendarDate represents a date without any time components in a specific calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	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.
`day`	`number`	The day number within the month.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDate`	Returns a copy of this date.
`add( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration added to it.
`subtract( (duration: DateDuration )): CalendarDate`	Returns a new `CalendarDate` with the given duration subtracted from it.
`set( (fields: DateFields )): CalendarDate`	Returns a new `CalendarDate` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField, amount: number, options?: CycleOptions ): CalendarDate`	Returns a new `CalendarDate` 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 )): Date`	Converts the date to a native JavaScript Date object, with the time set to midnight in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: AnyCalendarDate )): number`	Compares 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.

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.

Properties

Name	Type	Description
`identifier`	`string`	A string identifier for the calendar, as defined by Unicode CLDR.

Methods

Method	Description
`fromJulianDay( (jd: number )): CalendarDate`	Creates a CalendarDate in this calendar from the given Julian day number.
`toJulianDay( (date: AnyCalendarDate )): number`	Converts a date in this calendar to a Julian day number.
`getDaysInMonth( (date: AnyCalendarDate )): number`	Returns the number of days in the month of the given date.
`getMonthsInYear( (date: AnyCalendarDate )): number`	Returns the number of months in the year of the given date.
`getYearsInEra( (date: AnyCalendarDate )): number`	Returns the number of years in the era of the given date.
`getEras(): string[]`	Returns a list of era identifiers for the calendar.
`getMinimumMonthInYear( (date: AnyCalendarDate )): number`	Returns the minimum month number of the given date's year. Normally, this is 1, but in some calendars such as the Japanese, eras may begin in the middle of a year.
`getMinimumDayInMonth( (date: AnyCalendarDate )): number`	Returns the minimum day number of the given date's month. Normally, this is 1, but in some calendars such as the Japanese, eras may begin in the middle of a month.

Name	Type	Description
`calendar`	`Calendar`
`era`	`string`
`year`	`number`
`month`	`number`
`day`	`number`

Method	Description
`copy():`

Represents an amount of time in calendar-specific units, for use when performing arithmetic.

Name	Type	Description
`years`	`number`	The number of years to add or subtract.
`months`	`number`	The number of months to add or subtract.
`weeks`	`number`	The number of weeks to add or subtract.
`days`	`number`	The number of days to add or subtract.

Name	Type	Description
`era`	`string`
`year`	`number`
`month`	`number`
`day`	`number`

Name	Type	Description
`round`	`boolean`	Whether to round the field value to the nearest interval of the amount.

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

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	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.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): CalendarDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields )): CalendarDateTime`	Returns a new `CalendarDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, 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 )): Date`	Converts the date to a native JavaScript Date object in the given time zone.
`toString(): string`	Converts the date to an ISO 8601 formatted string.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): number`	Compares 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.

Represents an amount of time with both date and time components, for use when performing arithmetic.

Name	Type	Description
`years`	`number`	The number of years to add or subtract.
`months`	`number`	The number of months to add or subtract.
`weeks`	`number`	The number of weeks to add or subtract.
`days`	`number`	The number of days to add or subtract.
`hours`	`number`	The number of hours to add or subtract.
`minutes`	`number`	The number of minutes to add or subtract.
`seconds`	`number`	The number of seconds to add or subtract.
`milliseconds`	`number`	The number of milliseconds to add or subtract.

'compatible'
  | 'earlier'
  | 'later'
  | 'reject'

A ZonedDateTime represents a date and time in a specific time zone and calendar system.

Properties

Name	Type	Description
`calendar`	`Calendar`	The calendar system associated with this date, e.g. Gregorian.
`era`	`string`	The calendar era for this date, e.g. "BC" or "AD".
`year`	`number`	The year of this date within the era.
`month`	`number`	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.
`day`	`number`	The day number within the month.
`hour`	`number`	The hour in the day, numbered from 0 to 23.
`minute`	`number`	The minute in the hour.
`second`	`number`	The second in the minute.
`millisecond`	`number`	The millisecond in the second.
`timeZone`	`string`	The IANA time zone identifier that this date and time is represented in.
`offset`	`number`	The UTC offset for this time, in seconds.

Methods

Method	Description
`constructor( (...args: any[] )): void`
`copy(): ZonedDateTime`	Returns a copy of this date.
`add( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration added to it.
`subtract( (duration: DateTimeDuration )): void`	Returns a new `ZonedDateTime` with the given duration subtracted from it.
`set( (fields: DateFields & & TimeFields, , disambiguation?: Disambiguation )): void`	Returns a new `ZonedDateTime` with the given fields set to the provided values. Other fields will be constrained accordingly.
`cycle( field: DateField \| \| TimeField, amount: number, options?: CycleTimeOptions ): void`	Returns a new `ZonedDateTime` with the given field adjusted by a specified amount. When the resulting value reaches the limits of the field, it wraps around.
`toDate(): void`	Converts the date to a native JavaScript Date object.
`toString(): void`	Converts the date to an ISO 8601 formatted string, including the UTC offset and time zone identifier.
`toAbsoluteString(): void`	Converts the date to an ISO 8601 formatted string in UTC.
`compare( (b: CalendarDate \| CalendarDateTime \| ZonedDateTime )): void`	Compares 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.

Converts a date value to a ZonedDateTime in the provided time zone. The disambiguation option can be set to control how values that fall on daylight saving time changes are interpreted.

toZoned(
  date: CalendarDate
    | CalendarDateTime
    | ZonedDateTime,
  timeZone: string,
  disambiguation?: Disambiguation
): ZonedDateTime