native-dates

API / Functions

time() function

Create a Time from a 12-hour or 24-hour clock string, numbers, fields, or a timestamp.

import { time } from 'native-dates'core 7.3 kB min+br

Reading clock times

time()

time(input, options?): Time
time(input, zone?): Time
time(hour, minute?, second?): Time

Creates a Time from a clock string, whole-number clock parts, a fields object, or a timestamp. Missing inputs throw a TypeError instead of defaulting to the current clock.

clock.js
import { datetime, time } from 'native-dates';

const morning = time('9am');
const closing = time('5:30pm');
const iso = time('17:30:00');
const fromNumbers = time(9, 30);
const fromFields = time({ hour: 17, minute: 30, millisecond: 250 });
const fromMoment = time(datetime('2026-11-16T17:30:00Z', 'America/New_York'));
const fromTemporal = time(Temporal.PlainTime.from('08:15'));

closing.toString(); // '17:30:00'
fromMoment.toString(); // '12:30:00'

Parameters

inputTimeInput | numberrequired

Clock string, fields object, existing time or timestamp, or 24-hour hour from 0 to 23.

optionsZone | ReadOptions | number

Time zone or options object when reading a Date or loose string, or minute from 0 to 59.

3 options
zoneZone

Time zone used to extract the time of day from a JavaScript Date or loose timestamp.

loosebooleandefault false

Read full timestamp strings and return null on unreadable input with @native-dates/plugins/loose.

dayFirstboolean

Interpret ambiguous numeric dates day-first when loose mode parses a date-and-time string.

secondnumber

Whole second from 0 to 59 when passing numbers. Write sub-second digits in a string or fields object.

Returns

Time

A Time representing a time of day, or null when loose mode cannot read input.

When the loose plugin is loaded, loose mode extracts the local clock from full timestamp strings. Unreadable inputs return null instead of throwing:

import { time } from 'native-dates';
import '@native-dates/plugins/loose';

time('2026-11-16T17:30:00Z', { zone: 'America/New_York', loose: true })?.toString(); // '12:30:00'
time('whenever', { loose: true }); // null

Accepted inputs

Twelve-hour strings accept hours from 1 through 12 followed by AM or PM. Midnight is 12 AM and noon is 12 PM.

Input Example How it reads
12-hour clock string '9am', '5:30pm', '12:15 a.m.' Reads hours 1 through 12 with am or pm and optional minutes, seconds, and fractions.
24-hour clock string '09:00', '17:30:00', '17:30:15.250' Reads 24-hour clock strings down to nanosecond precision.
Clock numbers time(9), time(9, 30), time(17, 30, 15) Takes whole numbers for hour, optional minute, and optional second.
Fields object { hour: 9, minute: 30, millisecond: 250 } Reads singular or plural clock fields and rejects out-of-range numbers.
DateTime or Temporal dt, Temporal.PlainTime, Temporal.ZonedDateTime Extracts the local time of day directly.
JavaScript Date time(jsDate, 'America/New_York') Reads the clock time of that instant in the given zone or configured default.

Reading the current time of day

Read the live clock in any time zone via now(), such as now('Europe/Berlin').time.

Edit this pageUpdated Nov 12, 2026