intl-dateformat - Format a date using Intl.DateTimeFormat goodness (i18n, timezo...

Format a date using Intl.DateTimeFormat goodness.

intl-dateformatis a simple date formatting library that leverage the Intl.DateTimeFormat API to format dates in different languages and timezones without having to clutter your JavaScript bundles.

Features

• ✌ Small : As it directly leverages Intl.DateTimeFormat , there is no need to bundle additional locales or a timezones database. It's already in your Browser!
• :ok_hand: Simple : It suppors a subset of ISO 8601 formats, discarding very rarely used date parts.
• Extensible : That said, if you want to customize things you can pass.

Installation

$ npm install intl-dateformat

Example

import formatDate from 'intl-formatdate'

const date = new Date(Date.UTC(1984, 0, 17, 16, 13, 37, 0))

formatDate(date, 'YYYY-MM-DD hh:mm:ss A')
// → 1984-01-17 04:13:37 PM
formatDate(date, 'YYYY, MMMM dddd DD')
// → 1984, January Tuesday 17
formatDate(date, 'YYYY-MM-DD hh:mm:ss A', { timezone: 'Asia/Singapore' })
// → 1984-01-18 00:13:37 AM
formatDate(date, 'YYYY, MMMM dddd DD', { locale: 'fr' })
// → 1984, Janvier Mercredi 18

Usage

import formatDate from 'intl-dateformat'

const date = new Date(Date.UTC(1984, 0, 17, 16, 13, 37, 0))

formatDate(date, 'YYYY-MM-DD hh:mm:ss A')
// → 1984-01-17 04:13:37 PM

Argument Description Type date The date to format Date , number format The mask used to format options Custom locale or timezone

Formats

Mask Description Example YYYY 4-digits year 1984 YY 2-digits year 84 MMMM Month name January MMM Short month name Jan DD 2-digits day 17 dddd Day of the week Tuesday ddd Short day of the week Tue A Day period AM , PM a Lowercased day period am , pm HH 24-hours hour 16 hh 12-hours hour 04 mm 2-digit minute 13 ss 2-digit second 37

Options

• locale - A BCP 47 tag to identify the output language
  • Type: string
  • Default: The system locale
  • Example: fr , fr-FR
• timezone - A IANA timezone
  • Type: string
  • Default: The system timezone
  • Example: Europe/Paris , America/Chicago

Custom formatters

If you find yourself missing some date parts, no problem we got you covered. You can create your own dateFormat function and add your custom formatters:

import { createDateFormatter } from 'intl-dateformat'

const formatDate = createDateFormatter({
  // numeric hour
  h: ({ hour }) => hour[0] === '0' ? hour[1] : hour
  // milliseconds
  SSS: (parts, date) => String(date.getTime()).slice(-3)
})

const date = new Date(Date.UTC(1984, 0, 17, 16, 13, 37, 0))

formatDate(date, 'YYYY-MM-DD h:mm:ss.SSS')
// → 1984-01-17 4:13:37.505

Argument Description Type formatters Custom formatters

Formatters

Formatters are represented as a dictionary of functions, where the key represents the mask that is to be matched in the format and the value is the function that will format the date.

The formatter function takes the following arguments:

• parts - An object containing all the date parts provided by Intl.DateTimeFormat . You can inspect the DatePartName type for an exhaustive list of all the date parts
• date - The original date passed to the formatDate function.