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 |