timeago.js

What is timeago.js?

timeago.js is a lightweight library used to format dates in a 'time ago' style, such as '3 minutes ago' or '2 days ago'. It is useful for displaying relative timestamps in a human-readable format.

What are timeago.js's main functionalities?

Basic Usage

This feature allows you to format the current date and time into a 'time ago' format. The code initializes a timeago instance and formats the current date.

const timeago = require('timeago.js');
const timeagoInstance = timeago();
console.log(timeagoInstance.format(new Date()));

Custom Locale

This feature allows you to register a custom locale for formatting dates. The code demonstrates how to create a custom locale and use it to format the current date.

const timeago = require('timeago.js');
const timeagoInstance = timeago();
timeago.register('my-locale', (number, index, totalSec) => [
  ['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]);
console.log(timeagoInstance.format(new Date(), 'my-locale'));

Live Updates

This feature allows you to automatically update the 'time ago' text as time passes. The code creates a DOM element, sets its datetime attribute, and uses timeago.js to render and update the text.

const timeago = require('timeago.js');
const timeagoInstance = timeago();
const element = document.createElement('div');
element.setAttribute('datetime', new Date().toISOString());
document.body.appendChild(element);
timeagoInstance.render(element);

Other packages similar to timeago.js

moment

Moment.js is a comprehensive library for parsing, validating, manipulating, and formatting dates. It offers more extensive date manipulation capabilities compared to timeago.js, but it is also larger in size.

date-fns

date-fns is a modern JavaScript date utility library that provides a wide range of functions for working with dates. It is modular and tree-shakeable, making it a lightweight alternative to Moment.js. It also includes functions for formatting dates in a 'time ago' style.

dayjs

Day.js is a minimalist JavaScript library that parses, validates, manipulates, and displays dates and times. It is similar to Moment.js but much smaller in size. It also supports relative time formatting similar to timeago.js.

README

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

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

Usage

• 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');

API

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(1544666010224);

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

// format date string
format('2018-12-12');

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

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

// e.g.
format(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:

<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
cancel();

// or cancel for the specific one
cancel(nodes[0])

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');

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