a tiny / simple library

What ?

timeago.js is a tiny(2kb) library used to format date with `*** time ago`. eg: '3 hours ago'. No dependency. and support automatically updating fuzzy timestamps (e.g. "4 minutes ago" or "about 1 day ago"). Download, view the examples, and enjoy.

You opened this page . (This will update automatically. Wait for it.)

Hustcc was born Aug 01, 1989.

Why ?

timeago.js was built to format date with `*** time ago` statement. You can test timeago.js here with the live demo.

How ?

First, load and install timeago.js library:

npm install timeago.js

Load timeago.js library file with script tag:

<script src="dist/timeago.js" type="text/javascript"></script>

Or you can use ES6 style:

import * as timeago from 'timeago.js';

Now, let's attach it to your timestamps on DOM ready:


This will realtime render all selected(javascript DOM selector) elements with a class of need_to_be_rendered.

<span class="need_to_be_rendered" datetime="2016-07-07T09:24:17Z">July 07, 2016</span>

You can also use it programmatically:

timeago.format(new Date());             //=> ""
timeago.format('2016-09-07', 'zh_CN')           //=> ""
timeago.format(1473245023718);          //=> ""

Locales register ?

Yes, timeago.js has locale/i18n/language support. Here are some configuration examples. Please submit a GitHub pull request for corrections or additional languages.

var locale = function(number, index, totalSec) {
  // number: the time ago / time in 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']
timeago.register('pt_BR', locale);
// then you can use it
timeago.format(1473245023718, 'pt_BR');

Where ?

Package is managed with npm. so npm install timeago.js will be the latest version.

The code is hosted on GitHub: http://github.com/hustcc/timeago.js. Go on, live on the edge.

Who ?

timeago.js was built by Hustcc while standing on the shoulders of giants.

What else ?

Other timeago, welcome to pull a request.

Do you use timeago.js ?

Great! Please let me know, and can add into the README.