Small & sweet date-range formatting
An opinionated library that makes date-ranges short and readable.
Introduction
When displaying date-ranges in UI, they are often too long and hard to read. This library tries to solve that problem.
little-date is a date-formatting library, based on date-fns. It aims to make date ranges short, readable and easy to understand.
It supports localization and can be used in both Node.js and the browser.
Examples dates ✨
Jan 1 - 12Jan 3 - Apr 20January 2023Q1 2023
Wasn't that easy to read? You can find a full list of formatting examples here.
Usage
import { formatDateRange } from "little-date";
const from = new Date("2023-01-01T00:00:00.000Z");
const to = new Date("2023-01-12T23:59:59.999Z");
formatDateRange(from, to); // Outputs: "Jan 1 - 12"Installation
With pnpm
pnpm i little-dateWith NPM
npm i little-dateFormatting Examples
| Description | Output |
|---|---|
| Multiple days, same month | Jan 1 - 12 |
| Multiple days, different months | Jan 3 - Apr 20 |
| Full day | Sun, Jan 1 |
| Range spanning different years | Jan 1 '22 - Jan 20 '23 |
| Multiple days, same month, different year | Jan 1 - 12, 2022 |
| Full day, different year | Sat, Jan 1, 2022 |
| Special cases | |
| Full year | 2023 |
| Quarter range | Q1 2023 |
| Full month | January 2023 |
| Full months | Jan - Feb 2023 |
| With time | |
| Today, different hours | 12am - 2:30pm |
| Same day, different hours | Jan 1, 12:11am - 2:30pm |
| Same day, different hours, 24-hour format | Jan 1, 0:11 - 14:30 |
| Hour difference within a day | Jan 1, 12pm - 12:59pm |
| Different days with time included | Jan 1, 12:11am - Jan 2, 2:30pm |
| Different years with time | Jan 1 '22, 12:11am - Jan 2 '23, 2:30pm |
| Different years, no time | Jan 1 '22 - Jan 2 '23 |
Advanced Options
Most of of the formatting behavior is opinionated and can't be changed. However, there are some options that can be used to customize the output.
import { formatDateRange } from "little-date";
// ...
formatDateRange(from, to, {
locale: "de-AT", // Overwrite the default locale
includeTime: false, // Prevent time from being displayed
today: new Date(), // Overwrite the default "today" date, useful for testing
separator: "-", // Overwrite the default separator. E.g. from "Jan 1 - 12" to "Jan 1 to 12"
});Contribute
We welcome contributions! If you'd like to improve little-date or have any feedback, feel free to open an issue or submit a pull request.
License
MIT