rc

Time

A Time represents a clock time without any date components.

installyarn add @internationalized/date
version3.0.0-rc.0
usageimport {Time} from '@internationalized/date'

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

NameTypeDescription
hournumberThe hour, numbered from 0 to 23.
minutenumberThe minute in the hour.
secondnumberThe second in the minute.
millisecondnumberThe millisecond in the second.

Methods

MethodDescription
constructor( hour: number, minute: number, second: number, millisecond: number ): void
copy(): TimeReturns a copy of this time.
add( (duration: TimeDuration )): voidReturns a new Time with the given duration added to it.
subtract( (duration: TimeDuration )): voidReturns a new Time with the given duration subtracted from it.
set( (fields: TimeFields )): voidReturns 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(): voidConverts the time to an ISO 8601 formatted string.
compare( (b: AnyTime )): voidCompares 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