small-date

A tiny (0.8kb) date formatting library with built-in i18n support.

Why?

There are several date formatting libraries out there. It all started with Moment, while nowadays smaller alternatives such as date-fns, DayJS and Luxon among others are raising in popularity.
While date-fns already comes in a really small format, it was still way to big for my most common use case: Format a date with a given pattern.
So I created this tiny library as an attempt to solve this specific problem with as little bytes as possible.

How it works

I was using Intl.DateTimeFormat previously and really liked it. So I had the idea to use that under the hood while providing a nice API that accepts a pattern in a widely used format.
The nice thing about Intl.DateTimeFormat is that it has built-in i18n support.

Browser Support

It works in all modern browsers.

However, if you need to support IE11, pick one of the libraries mentioned above!

Installation

yarn add small-date

Usage

The libraries exports a single function that accepts the following parameters:

Parameter	Type	Description
Date	Date	The date that is formatted
Pattern	string	The pattern in which the date should be formatted
Config	Object	A config option that accepts an locale and a timeZone

import { format } from 'small-date'

// Wednesday 03 March 2021, 11:45 am
format(new Date(), 'DDD dd MMMM yyyy, hh:mm a')

// Mittwoch 03 März 2021, 11:45
format(new Date(), 'DDD dd MMMM yyyy, HH:mm', {
  locale: 'de-DE',
})

Escaping Text

Sometimes we want to add arbitary text into our pattern. The problem is: Words break if they include tokens. Therefore, it is safest to escape all words with " quotes.

import { format } from 'small-date'

// Today is Wednesday the 03. of March
format(new Date(), '"Today is" DDD "the" dd. "of" MMMM')

TimeZone

We can pass a timeZone to the configuration to get the locale date at this particular zone.

import { format } from 'small-date'

// Wednesday 03 March 2021, 09:45 pm
format(new Date(), 'DDD dd MMMM yyyy, hh:mm a', {
  timeZone: 'Australia/Sydney',
})

Pattern Tokens

All examples below use the following date: new Date(2021, 2, 3, 18, 7, 8, 9) and the en-US locale.

Token	Description	Example
D	Weekday, 1 letter	W
DD	Weekday, 3 letters	Wed
DDD	Weekday, long	Wednesday
d	Day of the month, no padding	3
dd	Day of the month, padded to 2	03
M	Month, numeric	3
MM	Month, 2 digits	03
MMM	Month, 3 letters	Mar
MMMM	Month, long	March
y	Year, numeric	2021
yy	Year, 2 digits	21
yyyy	Year, numeric	2021
h	Hours, no padding	6
hh	Hours, padded to 2	06
H	Hours in 24-format, no padding	18
HH	Hours in 24-format, padded to 2	18
m	Minutes, no padding	7
m	Minutes, padded to 2	07
s	Seconds, no padding	8
ss	Seconds, padded to 2	08
S	Milliseconds, no padding	9
SS	Milliseconds, padded to 2	09
SSS	Milliseconds, padded to 3	009
G	Era, narrow	A
GG	Era, short	AD
GGG	Era, long	Anno Domino
Z	Time zone, short	GMT+1
ZZ	Time short, long	Central European Standard Time
P	Period of the day, narrow	in the morning
PP	Period of the day, short	in the morning
PPP	Period of the day, long	in the morning
a	Meridiem	pm

License

small-date is licensed under the MIT License.
Documentation is licensed under Creative Common License.
Created with ♥ by @robinweser and all the great contributors.