Lightweight Human Readable Date & Time Library – timeago.js

Category: Date & Time , Javascript , Recommended | October 12, 2019
Views Total:1,082 views
Official Page:Go to website
Last Update:October 12, 2019


Lightweight Human Readable Date & Time Library – timeago.js


timeago.js is a lightweight and pure JavaScript version of the familiar jQuery timeago plugin that allows to parse and format dates & times using natural language like ‘5 minutes ago’.

Basic usage:

Install and import the timeago.js in your web project.

npm install timeago.js
import { format, render, cancel, register } from 'timeago.js';
// or
import * as timeago from 'timeago.js';

Or load the JavaScript library from a CDN.

<script src=""></script>

Format a specified date time as follow:

// timestamp
// date object
format(new Date(1544666010224));
// date string
// with locale
format(1544666010224, 'en_US');
// with locale and relative date
format(1544666010224, 'en_US', '2019-10-12');
// returns '12 hours ago'
format( - 12 * 1000 * 60 * 60);

Format and render the date & time inside a specific container.

<div class="demo" data-timeago="2016-09-12 00:20:00"></div>

Customize the output strings.

// the local dict example is below.
const localeFunc = (number: number, index: number, totalSec: number): [string, string] => {
  // number: the timeago / timein number;
  // index: the index of array below;
  // totalSec: total seconds between date to be formatted and today's date;
  return [
    ['just now', 'right now'],
    ['%s seconds ago', 'in %s seconds'],
    ['1 minute ago', 'in 1 minute'],
    ['%s minutes ago', 'in %s minutes'],
    ['1 hour ago', 'in 1 hour'],
    ['%s hours ago', 'in %s hours'],
    ['1 day ago', 'in 1 day'],
    ['%s days ago', 'in %s days'],
    ['1 week ago', 'in 1 week'],
    ['%s weeks ago', 'in %s weeks'],
    ['1 month ago', 'in 1 month'],
    ['%s months ago', 'in %s months'],
    ['1 year ago', 'in 1 year'],
    ['%s years ago', 'in %s years']
// register your locale with timeago
register('my-locale', localeFunc);
// use it
format('2016-06-12', 'my-locale');



  • v4.0.0-beta.3: refactor: rewrite with typescript, remove jquery support


  • v4.0.0-beta.2


  • v4.0.0


  • v3.0.2

You Might Be Interested In:

Leave a Reply