Tiny (0.8kb) date formatting library with built-in i18n
npm install small-dateA tiny (0.8kb) date formatting library with built-in i18n support.
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.
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.
It works in all modern browsers.
> However, if you need to support IE11, pick one of the libraries mentioned above!
``sh`
yarn add small-date
The libraries exports a single function that accepts the following parameters:
| Parameter | Type | Description |
| --------- | --------- | --------------------------------------------------------- |
| Date | Date | The date that is formatted |string
| Pattern | | The pattern in which the date should be formatted |Object
| Config | | A config option that accepts a locale and a timeZone |
`javascript
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',
})
`
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.
`javascript
import { format } from 'small-date'
// Today is Wednesday the 03. of March
format(new Date(), '"Today is" DDD "the" dd. "of" MMMM')
`
We can pass a timeZone to the configuration to get the locale date at this particular zone.
`javascript
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',
})
`
> 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 |Wed
| DD | Weekday, 3 letters | |Wednesday
| DDD | Weekday, long | |3
| d | Day of the month, no padding | |03
| dd | Day of the month, padded to 2 | |3
| M | Month, numeric | |03
| MM | Month, 2 digits | |Mar
| MMM | Month, 3 letters | |March
| MMMM | Month, long | |2021
| y | Year, numeric | |21
| yy | Year, 2 digits | |2021
| yyyy | Year, numeric | |6
| h | Hours, no padding | |06
| hh | Hours, padded to 2 | |18
| H | Hours in 24-format, no padding | |18
| HH | Hours in 24-format, padded to 2 | |7
| m | Minutes, no padding | |07
| m | Minutes, padded to 2 | |8
| s | Seconds, no padding | |08
| ss | Seconds, padded to 2 | |9
| S | Milliseconds, no padding | |09
| SS | Milliseconds, padded to 2 | |009
| SSS | Milliseconds, padded to 3 | |A
| G | Era, narrow | |AD
| GG | Era, short | |Anno Domino
| GGG | Era, long | |GMT+1
| Z | Time zone, short | |Central European Standard Time
| ZZ | Time short, long | |in the morning
| P | Period of the day, narrow | |in the morning
| PP | Period of the day, short | |in the morning
| PPP | Period of the day, long | |pm` |
| a | Meridiem |
small-date is licensed under the MIT License.
Documentation is licensed under Creative Common License.
Created with ♥ by @robinweser and all the great contributors.