timeago.js

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 just now. (This will update automatically. Wait for it.)

Hustcc was born 32 years ago.

Why ?

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

Avoid timestamps dated "1 minute ago" even though the page was opened 10 minutes ago; timeago refreshes automatically.
You can take full advantage of page caching in your web applications, because the timestamps aren't calculated on the server.
Very tiny(less than 2kb), and has no dependency, e.g. jQuery.

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 timeago from 'timeago.js';
// or
var timeago = require("timeago.js");

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

timeago().render(document.querySelectorAll('.need_to_be_rendered'));
// or use jquery selector
timeago().render($('.need_to_be_rendered'));

This will realtime render all selected(javascript DOM selector, or jQuery selector all are supported) 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());             //=> "just now"
timeago(null, 'zh_CN').format('2016-09-07')           //=> "8年前"
timeago().format(1473245023718);          //=> "8 years ago"

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, total_sec) {
  // number: the timeago / timein number;
  // index: the index of array below;
  // total_sec: 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];
};
timeago.register('pt_BR', locale);
var timeagoInstance = timeago();
// then you can use it
timeagoInstance.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 ?

timeago.js for react: timeago-react is here
timeago for python: timeago is here

Other timeago, welcome to pull a request.

Do you use timeago.js ?

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