Package Exports

small-date
small-date/es/index.js
small-date/lib/index.js

This package does not declare an exports field, so the exports above have been automatically detected and optimized by JSPM instead. If any package subpath is missing, it is recommended to post an issue to the original package (small-date) to support the "exports" field. If that is not possible, create a JSPM override to customize the exports field for this package.

Readme

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 a `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.