parseJSON

Parse a JSON date string

Description

Converts a complete ISO date string in UTC time, the typical format for transmitting a date in JSON, to a JavaScript Date instance.

This is a minimal implementation for converting dates retrieved from a JSON API to a Date instance which can be used with other functions in the date-fns library. The following formats are supported:

• 2000-03-15T05:20:10.123Z: The output of .toISOString() and JSON.stringify(new Date())
• 2000-03-15T05:20:10Z: Without milliseconds
• 2000-03-15T05:20:10+00:00: With a zero offset, the default JSON encoded format in some other languages
• 2000-03-15T05:20:10+05:45: With a positive or negative offset, the default JSON encoded format in some other languages
• 2000-03-15T05:20:10+0000: With a zero offset without a colon
• 2000-03-15T05:20:10: Without a trailing 'Z' symbol
• 2000-03-15T05:20:10.1234567: Up to 7 digits in milliseconds field. Only first 3 are taken into account since JS does not allow fractional milliseconds
• 2000-03-15 05:20:10: With a space instead of a 'T' separator for APIs returning a SQL date without reformatting

For convenience and ease of use these other input types are also supported via [toDate]{@link https://date-fns.org/docs/toDate}:

• A Date instance will be cloned
• A number will be treated as a timestamp

Any other input type or invalid date strings will return an Invalid Date.

Usage

// CommonJS
var parseJSON = require('date-fns/parseJSON')

// ES 2015
import parseJSON from 'date-fns/parseJSON'

// ESM
import { parseJSON } from 'date-fns'

Syntax

parseJSON(argument)

Arguments

Name	Description
argument	A fully formed ISO8601 date string to convert

Returns

Description
the parsed date in the local time zone

Exceptions

Type	Description
TypeError	1 argument required