ISO 8601 Date Format: UTC, Timestamps & JavaScript

isoformat is a zero-dependency JavaScript utility that formats dates as the shortest equivalent ISO 8601 UTC string and parses supported ISO date or date-time strings into Date objects.

ISO 8601 represents a calendar date as YYYY-MM-DD and a UTC timestamp as YYYY-MM-DDTHH:MM:SSZ. JavaScript’s native Date.prototype.toISOString() always returns the full UTC date-time string. isoformat removes time components that equal zero. A midnight UTC value such as 2001-01-01T00:00:00.000Z becomes 2001-01-01.

ISO 8601 Date and Time Format Examples

ISO 8601 orders date and time components from the largest unit to the smallest unit. Hyphens separate calendar fields, a literal T starts the time section, and a time zone designator identifies the offset from UTC.

What T, Z, UTC, and Offsets Mean

• T separates the calendar date from the clock time.
• Z identifies UTC, also called Zulu time.
• +05:30 identifies a local clock that runs five hours and thirty minutes ahead of UTC.
• -04:00 identifies a local clock that runs four hours behind UTC.
• A date-only string such as 2026-07-26 contains no clock time or explicit offset.

The full ISO 8601 standard also defines week dates, ordinal dates, durations, intervals, and other representations. isoformat focuses on calendar dates and date-times that work with the JavaScript Date constructor.

ISO 8601 in JavaScript

Convert a JavaScript Date to an ISO String

Date.prototype.toISOString() returns a UTC string with seconds and milliseconds. The result uses Z as the UTC designator.

const publishedAt = new Date(Date.UTC(2026, 6, 26, 9, 30, 45, 123));
publishedAt.toISOString();
// "2026-07-26T09:30:45.123Z"

Get a YYYY-MM-DD Date String

Slice the first ten characters when a UTC calendar date is enough. This operation uses the UTC date, which may differ from the user’s local date near midnight.

const publishedAt = new Date(Date.UTC(2026, 6, 26, 9, 30));
const isoDate = publishedAt.toISOString().slice(0, 10);
console.log(isoDate);
// "2026-07-26"

Parse ISO 8601 Strings with the Date Constructor

JavaScript treats a date-only ISO string as UTC. A date-time string with no Z or numeric offset uses the runtime’s local time zone. Add Z or an offset when the value represents an absolute instant.

new Date("2026-07-26");
// 2026-07-26 at 00:00:00 UTC
new Date("2026-07-26T09:30");
// 09:30 in the runtime's local time zone
new Date("2026-07-26T09:30Z");
// 09:30 UTC
new Date("2026-07-26T09:30:00+05:30");
// Converted from the stated +05:30 offset

isoformat vs Date.prototype.toISOString()

The native method returns a fixed full-precision UTC string. isoformat returns the shortest equivalent UTC representation and keeps seconds or milliseconds only when the value requires them.

import {format} from "isoformat";
const midnight = new Date(Date.UTC(2001, 0, 1));
midnight.toISOString();
// "2001-01-01T00:00:00.000Z"
format(midnight);
// "2001-01-01"
const minutePrecision = new Date(Date.UTC(2026, 6, 26, 9, 30));
minutePrecision.toISOString();
// "2026-07-26T09:30:00.000Z"
format(minutePrecision);
// "2026-07-26T09:30Z"
const secondPrecision = new Date(Date.UTC(2026, 6, 26, 9, 30, 45));
format(secondPrecision);
// "2026-07-26T09:30:45Z"

Use toISOString() when an API or database expects a fixed UTC timestamp. Use isoformat when compact calendar dates and concise UTC timestamps improve CSV exports, serialized data, logs, or human-readable interchange files.

Features

• Shortest equivalent ISO 8601 UTC output.
• Calendar date, minute, second, and millisecond precision.
• Date objects and Unix millisecond timestamps as formatter inputs.
• Calendar date and date-time parsing through the native Date constructor.
• UTC, colon-separated offsets, and compact numeric offsets.
• Fallback values and fallback functions.
• Expanded positive and negative year notation.
• ES module package with no runtime dependencies.

Use Cases

• CSV exports keep midnight values as readable calendar dates.
• API serializers remove empty seconds and milliseconds from optional-precision fields.
• Import scripts accept supported UTC and offset date-time strings from multiple systems.
• Data cleanup jobs route unsupported input through a fallback value or error function.

How To Use isoformat

Install the Package

Install isoformat from npm. The package uses ES modules and exports format and parse.

npm install isoformat

Basic Usage

import {format, parse} from "isoformat";
const releaseDate = new Date(Date.UTC(2026, 6, 26));
console.log(format(releaseDate));
// "2026-07-26"
const parsedDate = parse("2026-07-26T09:30Z");
console.log(parsedDate.toISOString());
// "2026-07-26T09:30:00.000Z"

Format a Date or Unix Timestamp

The formatter accepts a Date instance or a number that represents milliseconds since the Unix epoch.

import {format} from "isoformat";
const scheduledAt = new Date(Date.UTC(2026, 6, 26, 9, 30, 45, 123));
console.log(format(scheduledAt));
// "2026-07-26T09:30:45.123Z"
const unixMilliseconds = Date.UTC(2026, 6, 26, 9, 30);
console.log(format(unixMilliseconds));
// "2026-07-26T09:30Z"

Parse UTC and Offset Date-Time Strings

The parser accepts Z, colon-separated offsets, and compact four-digit offsets. It returns a native Date instance.

import {parse} from "isoformat";
parse("2026-07-26T09:30Z");
parse("2026-07-26T09:30:45+05:30");
parse("2026-07-26T09:30:45-0400");

Handle Unsupported Input

Pass a fallback value when the input does not match the supported format. A fallback function receives the rejected input.

import {format, parse} from "isoformat";
format(new Date(NaN), null);
// null
parse("2026-W30-7", null);
// null
parse("not-a-date", (value) => {
  throw new RangeError(`Unsupported ISO date: ${value}`);
});

Supported Output Formats

format() always produces a UTC value. It starts with a full calendar date and adds only the required time precision.

Years outside 0000 through 9999 use signed six-digit notation such as +020000 or -000020. The formatter does not return year-only or year-month strings.

Supported Parse Formats

parse() accepts the following calendar date and date-time shapes. A signed six-digit expanded year may replace YYYY.

Replace Z with +HH:MM, -HH:MM, +HHMM, or -HHMM for a numeric time zone offset. The parser does not accept an hour-only offset such as +05.

API Reference

format(date, fallback)

Formats a date as the shortest equivalent ISO 8601 UTC string.

• date accepts a Date instance or Unix time in milliseconds.
• fallback accepts any value or a function. The default value is undefined.
• The fallback function receives an invalid Date instance.
• The return value is a string or the supplied fallback result.

import {format} from "isoformat";
// Format a Date.
format(new Date(Date.UTC(2026, 6, 26)));
// Format Unix milliseconds.
format(Date.UTC(2026, 6, 26, 9, 30));
// Return a custom value for an invalid date.
format(NaN, "Invalid date");

parse(string, fallback)

Checks a string against the supported pattern and passes matching input to the native Date constructor.

• string accepts a supported calendar date or date-time string.
• fallback accepts any value or a function. The default value is undefined.
• The fallback function receives the rejected input as a string.
• The return value is a native Date instance or the supplied fallback result.

import {parse} from "isoformat";
// Parse a calendar date.
parse("2026-07-26");
// Parse an offset date-time.
parse("2026-07-26T09:30:45+05:30");
// Reject an unsupported week date.
parse("2026-W30-7", null);

How isoformat Works

The formatter reads each UTC date component and builds the result from left to right. It always writes the calendar date. It appends hours and minutes when the UTC time is not midnight, seconds when they are nonzero, and milliseconds when they are nonzero.

The parser first checks the input with a regular expression that describes the supported calendar date and date-time shapes. Matching input then goes to the native JavaScript Date constructor. This approach keeps the package small and gives the returned value standard Date methods.

Limitations and Parsing Notes

• Date-time input with no Z or numeric offset uses the runtime’s local time zone.
• Date-only, year-month, and year-only input follows the native Date constructor’s UTC behavior.
• Fractional seconds require exactly three digits.
• Week dates, ordinal dates, time-only values, durations, and intervals fall outside the supported parser subset.
• The parser checks the string shape, then relies on the native Date constructor for calendar conversion.
• The native Date constructor may normalize some out-of-range calendar values. Add a separate validation step when exact rejection matters.
• A matching string may still produce an Invalid Date. The parse fallback handles a pattern mismatch, not every invalid native Date result.

Alternatives and Related Resources

• Lightweight Date & Time Manipulation Library – Day.js
• Format JavaScript Date Strings – format-date
• Convert Dates Between Time Zones – minitz.js
• Get Date Information With The Easy Dates Library
• JavaScript & CSS Date Format Resources
• Date.prototype.toISOString()

FAQs

Q: What is the standard ISO 8601 date format?
A: The common calendar date format is YYYY-MM-DD, such as 2026-07-26. A UTC date-time commonly uses YYYY-MM-DDTHH:MM:SSZ.

Q: What does Z mean in an ISO 8601 timestamp?
A: Z means the value uses UTC. A numeric offset such as +05:30 identifies a local clock relative to UTC.

Q: How do I convert a JavaScript Date to an ISO string?
A: Call date.toISOString() for a fixed full-precision UTC string. Call format(date) from isoformat for the shortest equivalent UTC representation.

Q: Does isoformat parse ISO 8601 time zone offsets?
A: Yes. parse() accepts Z, +HH:MM, -HH:MM, +HHMM, and -HHMM on supported date-time strings.

Q: Is isoformat a full ISO 8601 validator?
A: No. It supports a focused calendar date and date-time subset, checks the string shape, and delegates conversion to the native Date constructor.