js-ago

Simple "time" ago for your JavaScript Date objects.

Installation

npm install js-ago

or

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 accepted by Intl.RelativeTimeFormat.

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:

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