packages/@internationalized/date/docs/Time.mdx
{/* Copyright 2020 Adobe. All rights reserved. This file is licensed to you under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License. You may obtain a copy of the License at http://www.apache.org/licenses/LICENSE-2.0 Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR REPRESENTATIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License. */}
import {Layout} from '@react-spectrum/docs'; export default Layout;
import docs from 'docs:@internationalized/date'; import {HeaderInfo, FunctionAPI, ClassAPI, TypeContext, InterfaceType, TypeLink, PageDescription} from '@react-spectrum/docs'; import packageData from '@internationalized/date/package.json';
<PageDescription>{docs.exports.Time.description}</PageDescription>
<HeaderInfo packageData={packageData} componentNames={['Time']} sourceData={[]} />
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);
You can also create a Time by parsing an ISO 8601 formatted string using the <TypeLink links={docs.links} type={docs.exports.parseTime} /> function.
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'
A <TypeLink links={docs.links} type={docs.exports.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
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.
The <TypeLink links={docs.links} type={docs.exports.parseDuration} /> function can be used to convert a ISO 8601 duration string into a <TypeLink links={docs.links} type={docs.exports.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('PT20H35M15S')
// => {hours: 20, minutes: 35, seconds: 15}
parseDuration('-PT20H35M15S')
// => {hours: -20, minutes: -35, seconds: -15}
parseDuration('PT20H35M15,75S')
// => {hours: 20, minutes: 35, seconds: 15.75}
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
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
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);
time.cycle('hour', 1); // 00:59
time.cycle('minute', 1); // 23:00
let time = new Time(0, 0);
time.cycle('hour', -1); // 23:00
time.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
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
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'
A Time can be combined with a CalendarDate to produce a CalendarDateTime object using the <TypeLink links={docs.links} type={docs.exports.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
A <TypeLink links={docs.links} type={docs.exports.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 <TypeLink links={docs.links} type={docs.exports.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 <TypeLink links={docs.links} type={docs.exports.toZoned} /> function can be used to convert a CalendarDateTime to a ZonedDateTime.
import {toZoned, toCalendarDateTime, CalendarDate} 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]
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