# tiny-relative-date

> Tiny function that provides relative, human-readable dates.

Latest version **2.0.2** (published 2025-06-17) · MIT license · 0 weekly downloads

## Install

```sh
npm install tiny-relative-date
pnpm add tiny-relative-date
yarn add tiny-relative-date
bun add tiny-relative-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.2 |
| Published | 2025-06-17 |
| First published | 2017-06-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 22.2 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 19 |
| Author | Joseph Wynn |
| Maintainers | wildlyinaccurate |

## Links

- npm: https://www.npmjs.com/package/tiny-relative-date
- Repository: https://github.com/wildlyinaccurate/relative-date
- Homepage: https://github.com/wildlyinaccurate/relative-date#readme
- Issues: https://github.com/wildlyinaccurate/relative-date/issues
- npm.io page: https://npm.io/package/tiny-relative-date

## Recent versions

- 2.0.2 (latest) — 2025-06-17
- 2.0.1 — 2025-06-17
- 1.3.0 — 2017-07-16
- 1.2.0 — 2017-07-16
- 1.1.0 — 2017-07-02
- 1.0.2 — 2017-06-30
- 1.0.1 — 2017-06-25
- 1.0.0 — 2017-06-25

## README

<h1><sup><small>(Tiny)</small></sup> Relative Date</h1>

Tiny function that provides relative, localised, human-readable dates.

![npm bundle size (minified + gzip)](https://img.shields.io/bundlephobia/minzip/tiny-relative-date.svg?style=for-the-badge)
![Monthly Downloads](https://img.shields.io/npm/dm/tiny-relative-date.svg?style=for-the-badge)
![Build Status](https://img.shields.io/travis/wildlyinaccurate/tiny-relative-date.svg?style=for-the-badge)

## Installation

```
npm install tiny-relative-date
```

## Usage

The module returns a `relativeDate` function with English translations by default.

```js
const relativeDate = require('tiny-relative-date')
```

The `relativeDate` function accepts date strings or `Date` objects.

```js
relativeDate('2017-06-25 09:00') // '12 hours ago'
relativeDate(new Date()) // 'just now'
```

The value of "now" can also be passed as a second parameter.

```js
const now = new Date('2017-06-25 08:00:00')
const date = new Date('2017-06-25 07:00:00')

relativeDate(date, now) // 'an hour ago'
```

### Using a non-English locale

The tiny-relative-date module can be initialised with a locale. See the [translations directory](./translations) for a list of available locales.

```js
const relativeDateFactory = require('tiny-relative-date/lib/factory')
const deTranslations = require('tiny-relative-date/translations/de')
const relativeDate = relativeDateFactory(deTranslations)

relativeDate(new Date()) // 'gerade eben'
```

### Using a custom locale

You can also use a completely custom locale by passing a translations object instead of a locale string. Translations can be plain strings with a `{{time}}` placeholder, or they can be functions. See the **Adding new locales** section below for a list of translation keys.

```js
const relativeDateFactory = require('tiny-relative-date/lib/factory')
const relativeDate = relativeDateFactory({
  hoursAgo: '{{time}}h ago',
  daysAgo: (days) => `${days * 24}h ago`
})

relativeDate('2017-06-25 07:00:00') // '2h ago'
relativeDate('2017-06-24 06:00:00') // '27h ago'
```

## Contributing

Contributions are welcome! Running this project locally requires Git and Node.js.

```
git clone git@github.com:wildlyinaccurate/tiny-relative-date.git
cd tiny-relative-date/
npm install
```

Once you are set up, you can make changes to files in the `src/`, `spec/` and `translations/` directories. Build any changes you make by running

```
npm run build
```

And run the tests with

```
npm run test
```

### Adding new locales

If you would like to add a new locale, please create a JSON file in the `translations` directory and ensure it has the following keys:

| Key                    | Default value ("en" locale) |
|------------------------|-----------------------------|
| `justNow`             | just now                    |
| `secondsAgo`          | {{time}} seconds ago        |
| `aMinuteAgo`         | a minute ago                |
| `minutesAgo`          | {{time}} minutes ago        |
| `anHourAgo`          | an hour ago                 |
| `hoursAgo`            | {{time}} hours ago          |
| `aDayAgo`            | yesterday                   |
| `daysAgo`             | {{time}} days ago           |
| `aWeekAgo`           | a week ago                  |
| `weeksAgo`            | {{time}} weeks ago          |
| `aMonthAgo`          | a month ago                 |
| `monthsAgo`           | {{time}} months ago         |
| `aYearAgo`           | a year ago                  |
| `yearsAgo`            | {{time}} years ago          |
| `overAYearAgo`      | over a year ago             |
| `secondsFromNow`     | {{time}} seconds from now   |
| `aMinuteFromNow`    | a minute from now           |
| `minutesFromNow`     | {{time}} minutes from now   |
| `anHourFromNow`     | an hour from now            |
| `hoursFromNow`       | {{time}} hours from now     |
| `aDayFromNow`       | tomorrow                    |
| `daysFromNow`        | {{time}} days from now      |
| `aWeekFromNow`      | a week from now             |
| `weeksFromNow`       | {{time}} weeks from now     |
| `aMonthFromNow`     | a month from now            |
| `monthsFromNow`      | {{time}} months from now    |
| `aYearFromNow`      | a year from now             |
| `yearsFromNow`       | {{time}} years from now     |
| `overAYearFromNow` | over a year from now        |

---
_Source: https://npm.io/package/tiny-relative-date · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._