# small-date
> Tiny (0.8kb) date formatting library with built-in i18n
Latest version **2.0.1** (published 2024-11-06) · MIT license · 0 weekly downloads
## Install
```sh
npm install small-date
pnpm add small-date
yarn add small-date
bun add small-date
```
## Health
**Score 40/100 (D)** — status: maintenance-mode.
Positive: has types; esm support; no vulnerabilities; high quality score.
Warnings: low downloads.
Negative: stale; low maintenance score.
## Facts
| | |
|---|---|
| Version | 2.0.1 |
| Published | 2024-11-06 |
| First published | 2021-10-05 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 15.7 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 13 |
| Author | Robin Weser |
| Maintainers | rofrischmann |
| Keywords | date, formatting, date-fns, datetime, format |
## Links
- npm: https://www.npmjs.com/package/small-date
- Repository: https://github.com/robinweser/small-date
- Issues: https://github.com/robinweser/small-date/issues
- npm.io page: https://npm.io/package/small-date
## Alternatives
- [@js-joda/timezone](https://npm.io/package/@js-joda/timezone.md) — 383.4K weekly downloads
- [chartjs-adapter-moment](https://npm.io/package/chartjs-adapter-moment.md) — 210.8K weekly downloads
- [strftime](https://npm.io/package/strftime.md) — 171.2K weekly downloads
- [vue-flatpickr-component](https://npm.io/package/vue-flatpickr-component.md) — 115.8K weekly downloads
- [timepicker](https://npm.io/package/timepicker.md) — 51.0K weekly downloads
## Recent versions
- 2.0.1 (latest) — 2024-11-06
- 2.0.0 — 2022-11-30
- 1.0.2 — 2021-11-26
- 1.0.1 — 2021-11-26
- 1.0.0 — 2021-10-05
## 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](https://momentjs.com), while nowadays smaller alternatives such as [date-fns](https://date-fns.org), [DayJS](https://day.js.org) and [Luxon](https://moment.github.io/luxon/#/) among others are raising in popularity.
While [date-fns](https://date-fns.org) 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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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
```sh
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` |
```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',
})
```
### 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.
```javascript
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.
```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',
})
```
## 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](http://opensource.org/licenses/MIT).
Documentation is licensed under [Creative Common License](http://creativecommons.org/licenses/by/4.0/).
Created with ♥ by [@robinweser](http://weser.io) and all the great contributors.
---
_Source: https://npm.io/package/small-date · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._