timeago.js

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.

Such as

1just now
212 seconds ago
32 hours ago
43 days ago
53 weeks ago
62 years ago
7
8in 12 seconds
9in 3 minutes
10in 24 days
11in 6 months

Usage

• install

1npm install timeago.js

• import

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

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

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

• example

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

CDN

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

1<script src="//unpkg.com/timeago.js"></script>

API

There only 4 API below.

• format

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

1import { format } from 'timeago.js';
2
3// format timestamp
4format(1544666010224);
5
6// format date instance
7format(new Date(1544666010224));
8
9// format date string
10format('2018-12-12');
11
12// format with locale
13format(1544666010224, 'zh_CN');
14
15// format with locale and relative date
16format(1544666010224, 'zh_CN', { relativeDate: '2018-11-11' });
17
18// e.g.
19format(Date.now() - 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])
cancel([dom])

Make a dom with datetime attribute automatic rendering and cancel.

HTML code:

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

Javascript code:

1import { render, cancel } from 'timeago.js';
2
3const nodes = document.querySelectorAll('.timeago');
4
5// use render method to render nodes in real time
6render(nodes, 'zh_CN');
7
8// render with opts
9// render(nodes, 'en_US', { minInterval: 3 });
10
11// cancel all real-time render task
12cancel();
13
14// or cancel for the specific one
15cancel(nodes[0])

The 3rd parameter opts contains:

1export type Opts = {
2  /** the relative date */
3  readonly relativeDate?: TDate;
4  /** the realtime min update interval */
5  readonly minInterval?: number;
6};

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.

1const localeFunc = (number: number, index: number, totalSec: number): [string, string] => {
2  // number: the timeago / timein number;
3  // index: the index of array below;
4  // totalSec: total seconds between date to be formatted and today's date;
5  return [
6    ['just now', 'right now'],
7    ['%s seconds ago', 'in %s seconds'],
8    ['1 minute ago', 'in 1 minute'],
9    ['%s minutes ago', 'in %s minutes'],
10    ['1 hour ago', 'in 1 hour'],
11    ['%s hours ago', 'in %s hours'],
12    ['1 day ago', 'in 1 day'],
13    ['%s days ago', 'in %s days'],
14    ['1 week ago', 'in 1 week'],
15    ['%s weeks ago', 'in %s weeks'],
16    ['1 month ago', 'in 1 month'],
17    ['%s months ago', 'in %s months'],
18    ['1 year ago', 'in 1 year'],
19    ['%s years ago', 'in %s years']
20  ][index];
21};
22// register your locale with timeago
23register('my-locale', localeFunc);
24
25// use it
26format('2016-06-12', 'my-locale');

Contributions

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.

LICENSE

MIT@hustcc