# js-ago

> Simple time ago for Unix timestamps and JavaScript Date objects.

Latest version **3.0.3** (published 2026-02-28) · MIT license · 0 weekly downloads

## Install

```sh
npm install js-ago
pnpm add js-ago
yarn add js-ago
bun add js-ago
```

## Health

**Score 55/100 (C)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 3.0.3 |
| Published | 2026-02-28 |
| First published | 2020-06-11 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 8.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 2 |
| Author | Arvin Ashtari |
| Maintainers | arvin7 |
| Keywords | relative time ago, javascript, time, ago, timeago, timestamp, unix-timestamp, timediff, date |

## Links

- npm: https://www.npmjs.com/package/js-ago
- Repository: https://github.com/Arvin7/js-ago
- Homepage: https://github.com/Arvin7/js-ago#readme
- Issues: https://github.com/Arvin7/js-ago/issues
- npm.io page: https://npm.io/package/js-ago

## 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

- 3.0.3 (latest) — 2026-02-28
- 3.0.1 — 2025-04-18
- 3.0.0 — 2025-04-18
- 2.1.2 — 2025-03-29
- 2.1.1 — 2024-02-05
- 2.1.0 — 2024-02-05
- 2.0.2 — 2023-01-31
- 2.0.1 — 2021-11-14
- 2.0.0 — 2021-11-14
- 1.1.0 — 2021-01-22
- 1.0.2 — 2020-06-19
- 1.0.1 — 2020-06-11
- 1.0.0 — 2020-06-11

## README

# js-ago

![Github issues](https://img.shields.io/github/issues/Arvin7/js-ago)
![GitHub stars](https://img.shields.io/github/stars/Arvin7/js-ago)
![GitHub license](https://img.shields.io/github/license/Arvin7/js-ago)
![NPM version](https://img.shields.io/npm/v/js-ago)
![NPM downloads](https://img.shields.io/npm/dt/js-ago)
![Twitter](https://img.shields.io/twitter/url?url=https%3A%2F%2Fgithub.com%2FArvin7%2Fjs-ago)

Simple "time" ago for your JavaScript Date objects.

## Installation

```shell script
npm install js-ago
```

or

```shell script
pnpm add js-ago
```

## Usage

The `jsAgo` function accepts two arguments: `jsAgo(timestamp[, options]);`

| Parameter | Required | Type                                                                      | Default                                                   | Possible Values                                                                                                                                                                                                                             |
| --------- | -------- | ------------------------------------------------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| timestamp | **yes**  | `Date`                                                                    |                                                           | A `Date()` object                                                                                                                                                                                                                           |
| options   | no       | `{ locale: Intl.LocalesArgument, style: "narrow" \|  "short" \| "long" }` | `{ locale: "en-US", style: "narrow", numeric: "always" }` | An optional object to set the locale, style and [other options](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Intl/RelativeTimeFormat/RelativeTimeFormat#options) accepted by `Intl.RelativeTimeFormat`. |

```javascript
import { jsAgo } from "js-ago";
// or
// const { jsAgo } = require('js-ago');

jsAgo(new Date("2024-03-16")); // 10mo ago

jsAgo(new Date("2024-03-16"), { style: "short" }); // 10 mon. ago

jsAgo(new Date("2024-03-16"), { style: "long" }); // 10 months ago
```

In a **React** component:

```jsx
import React from "react";
import { jsAgo } from "js-ago";

export function Article() {
  const dateInApiResponse = "2025-03-16T06:17:54.662Z";
  const createdAt = jsAgo(new Date(dateInApiResponse));

  return (
    <article>
      <h1>Post Title</h1>
      <p>Lorem ipsum...</p>
      <footer>Posted {createdAt}</footer> {/* Output: Posted 8m ago */}
    </article>
  );
}
```

## Outputs

As of version 3.0.0, you can pass different locale and get localised output.
The default locale (`en-US`) will output:

| narrow (default) | short | long   |
| ---------------- | ----- | ------ |
| s                | sec.  | second |
| m                | min.  | minute |
| h                | hr.   | hour   |
| d                | day   | day    |
| w                | wk.   | week   |
| mo               | mo.   | month  |
| y                | yr.   | year   |

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