ramkrishnatkr / timeago.js

:clock8: :hourglass: timeago.js is a tiny(~1.75kb) library used to format date with `*** time ago` statement. eg: '3 hours ago'. No dependency & localization & tiny.

timeago.js

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

• Localization supported.
• Time ago and time in supported.
• Real-time render supported.
• Nodejs and browserjs supported.
• Well tested.

Official website. 中文版说明文档点这里。 React version here: timeago-react. Python version here: timeago.

Such as

just now
12 seconds ago
3 minutes ago
2 hours ago
3 days ago
3 weeks ago
6 months ago
2 years ago

in 12 seconds
in 3 minutes
in 2 hours
in 24 days
in 6 months
in 2 years

1. Usage

1. Install timeago.js

npm install timeago.js

2. import timeago.js

ES6 style is supported, then get global object: timeago.

import timeago from 'timeago.js';

// or

var timeago = require("timeago.js");

or link with script in html files:

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

3. Use class timeago

var timeago = timeago();
timeago.format('2016-06-12')

2. Detailed Usage

1. Set relative date

timeago is relative to the current date default. You can set it yourself.

var timeago = timeago('2016-06-10 12:12:12'); // set the relative date here.
timeago.format('2016-06-12', 'zh_CN');

2. Use timestamp

timeago().format(new Date().getTime() - 11 * 1000 * 60 * 60); // will get '11 hours ago'

3. Automatic rendering

HTML code：

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

js code

// use render to render it in real time
timeago().render(document.querySelectorAll('.need_to_be_rendered'), 'zh_CN');
// or cancel realtime render
timeago().cancel()

The input API render should be DOM object/array, support pure Javascript, Node, and jQuery DOM object.

The API cancel will clear all the render timers and release all resources.

The DOM object should have the attribute data-timeago with date formated string.

4. Localization

Default locale is en, and the library supports en and zh_CN.

var timeago = timeago();
timeago.format('2016-06-12', 'zh_CN');

You can change the locale in the constructor or use the setLocale method;

var timeago = timeago(null, 'zh_CN');
// or
timeago().setLocale('zh_CN');

5. Register local language

You can register your own language. Like below, e.g.

// the local dict example is below.
var test_local_dict = function(number, index) {
  // number: the timeago / timein number;
  // index: the index of array below;
  return [
    ['just now', 'a while'],
    ['%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];
};

var timeago = timeago();
timeago.register('test_local', test_local_dict);

timeago.format('2016-06-12', 'test_local');

You can see locales dir for more locales.

Locale contributions are welcome, thank you for submitting a GitHub pull request for corrections or additional languages. ^_^~

3. Contributions

1. The website is based on rmm5t/jquery-timeago which is a nice and featured project but 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 en's translation.
• Please test the locale by exec npm test or node tests/locales_test.js. How to write testcase, see en's test cases.

4. LICENSE

MIT