Little-date NPM

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 - 12
Jan 3 - Apr 20
January 2023
Q1 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-date

With NPM

npm i little-date

Formatting 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"
});