Menu Close



timeago.js is a nano library(less than 2 kb) used to format datetime with *** time ago statement. eg: ‘3 hours ago’.

  • i18n supported.
  • Time ago and time in supported.
  • Real-time render supported.
  • Node and browser supported.
  • Well tested.

Official website. React version here: timeago-react. Python version here: timeago.

npm Version
Build Status
Coverage Status
Dist gzip
npm Download
npm License

Such as

just now
12 seconds ago
2 hours ago
3 days ago
3 weeks ago
2 years ago

in 12 seconds
in 3 minutes
in 24 days
in 6 months


  • install
npm install timeago.js
  • import
import { format, render, cancel, register } from 'timeago.js';

or import with script tag in html file and access global variable timeago.

<script src="dist/timeago.min.js"></script>
  • example

// format the time with locale
format('2016-06-12', 'en_US');


Alternatively to NPM, you can also use a CDN which will reflect the latest version as soon as it is published to npm.

<script src="//"></script>


There only 4 API below.

  • format

format(date[, locale = 'en_US', opts]), format a Date instance / timestamp / date string to string.

import { format } from 'timeago.js';

// format timestamp

// format date instance
format(new Date(1544666010224));

// format date string

// format with locale
format(1544666010224, 'zh_CN');

// format with locale and relative date
format(1544666010224, 'zh_CN', { relativeDate: '2018-11-11' });

// e.g.
format( - 11 * 1000 * 60 * 60); // returns '11 hours ago'

The default locale is en_US, and the library contains en_US and zh_CN build-in.

  • render & cancel

render(dom[, locale = 'en_US', opts])

Make a dom with datetime attribute automatic rendering and cancel.

HTML code:

<div class="timeago" datetime="2016-06-30 09:20:00"></div>

Javascript code:

import { render, cancel } from 'timeago.js';

const nodes = document.querySelectorAll('.timeago');

// use render method to render nodes in real time
render(nodes, 'zh_CN');

// render with opts
// render(nodes, 'en_US', { minInterval: 3 });

// cancel all real-time render task

// or cancel for the specific one

The 3rd parameter opts contains:

export type Opts = {
  /** the relative date */
  readonly relativeDate?: TDate;
  /** the realtime min update interval */
  readonly minInterval?: number;

The DOM object should have the attribute datetime with date formatted string.

  • register

register(locale, localeFunc), register a new locale, build-in locale contains: en_US, zh_CN, all locales here.

You can register your own language with register API.

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'] ][index]; }; // register your locale with timeago register('my-locale', localeFunc); // use it format('2016-06-12', 'my-locale');


  1. The website is based on rmm5t/jquery-timeago which is a nice and featured project but it depends on jQuery.
  2. locale translations: The library needs more locale translations. You can:
  • Open an issue to write the locale translations, or submit a pull request. How to ? see locales translation.
  • Please test the locale by exec npm test. How to write test cases, see locales test cases.



View Source Code
Posted in Development