javascript-time-ago
Advanced tools
Intelligent, international, higly customizable relative date/time formatter (both for past and future dates).
The `javascript-time-ago` npm package is used to format dates and times in a human-readable way, such as '5 minutes ago' or '2 days ago'. It supports multiple languages and locales, making it a versatile tool for internationalization.
Basic Usage
This feature allows you to format a date into a human-readable string indicating the time elapsed since that date. The example shows how to set up the package for English and format a date to '1 minute ago'.
const TimeAgo = require('javascript-time-ago');
const en = require('javascript-time-ago/locale/en');
TimeAgo.addLocale(en);
const timeAgo = new TimeAgo('en-US');
console.log(timeAgo.format(new Date(Date.now() - 60 * 1000))); // '1 minute ago'Custom Styles
This feature allows you to define custom styles for formatting the elapsed time. The example demonstrates how to create a custom style and use it to format a date.
const TimeAgo = require('javascript-time-ago');
const en = require('javascript-time-ago/locale/en');
TimeAgo.addLocale(en);
const timeAgo = new TimeAgo('en-US');
const customStyle = {
steps: [
{ formatAs: 'second' },
{ formatAs: 'minute' },
{ formatAs: 'hour' },
{ formatAs: 'day' },
{ formatAs: 'week' },
{ formatAs: 'month' },
{ formatAs: 'year' }
]
};
console.log(timeAgo.format(new Date(Date.now() - 60 * 1000), customStyle)); // '1 minute ago'Localization
This feature supports multiple languages and locales, allowing you to format dates in different languages. The example shows how to set up the package for both English and Spanish.
const TimeAgo = require('javascript-time-ago');
const en = require('javascript-time-ago/locale/en');
const es = require('javascript-time-ago/locale/es');
TimeAgo.addLocale(en);
TimeAgo.addLocale(es);
const timeAgoEn = new TimeAgo('en-US');
const timeAgoEs = new TimeAgo('es-ES');
console.log(timeAgoEn.format(new Date(Date.now() - 60 * 1000))); // '1 minute ago'
console.log(timeAgoEs.format(new Date(Date.now() - 60 * 1000))); // 'hace 1 minuto'Moment.js is a widely-used library for parsing, validating, manipulating, and formatting dates. It offers extensive functionality for date and time manipulation, but it is larger in size compared to `javascript-time-ago` and has been deprecated in favor of more modern solutions.
date-fns provides a comprehensive set of functions for working with dates in JavaScript. It is modular, allowing you to import only the functions you need, which can result in smaller bundle sizes. It also supports internationalization, similar to `javascript-time-ago`.
timeago.js is a small library used to format dates in a 'time ago' style. It is lightweight and easy to use, but it may not offer as many customization options or support for as many locales as `javascript-time-ago`.
Intelligent, international, higly customizable relative date/time formatter (both for past and future dates).
Automatically chooses the right units (seconds, minutes, etc) to format a time interval.
Examples:
For React users, there's a React component.
This is a readme for version 2.x. For older versions, see version 1.x readme. For migrating from version 1.x to version 2.x, see a migration guide.
npm install javascript-time-ago --save
import TimeAgo from 'javascript-time-ago'
// English.
import en from 'javascript-time-ago/locale/en'
TimeAgo.addLocale(en)
// Create formatter.
const timeAgo = new TimeAgo('en-US')
// Format dates using "round" style.
timeAgo.format(new Date(), 'round')
// "just now"
timeAgo.format(Date.now() - 15 * 1000, 'round')
// "15 seconds ago"
timeAgo.format(Date.now() - 60 * 1000, 'round')
// "1 minute ago"
timeAgo.format(Date.now() - 2 * 60 * 60 * 1000, 'round')
// "2 hours ago"
timeAgo.format(Date.now() - 24 * 60 * 60 * 1000, 'round')
// "1 day ago"
This library includes date/time formatting rules and labels for any language.
No languages are loaded default: a developer must manually choose which languages should be loaded. The languages should be imported from javascript-time-ago/locale and then added via TimeAgo.addLocale(...). An example of using Russian language:
import TimeAgo from 'javascript-time-ago'
// Russian.
import ru from 'javascript-time-ago/locale/ru'
TimeAgo.addLocale(ru)
const timeAgo = new TimeAgo('ru-RU')
// Format dates using "round" style.
timeAgo.format(new Date(), 'round')
// "только что"
timeAgo.format(Date.now() - 15 * 1000, 'round')
// "15 секунд назад"
timeAgo.format(Date.now() - 60 * 1000, 'round')
// "1 минуту назад"
timeAgo.format(Date.now() - 2 * 60 * 60 * 1000, 'round')
// "2 часа назад"
timeAgo.format(Date.now() - 24 * 60 * 60 * 1000, 'round')
// "1 день назад"
This library allows for any custom logic for formatting time intervals:
What scale should be used for measuring time intervals: should it be precise down to the second, or should it only measure it up to a minute, or should it start from being more precise when time intervals are small and then gradually decrease its precision as time intervals get longer.
What labels should be used: should it use the standard built-in labels for the languages ("... minutes ago", "... min. ago", "...m"), or should it use custom ones, or should it skip using relative time labels in some cases and instead output something like "Dec 11, 2015".
Such configuration comes under the name of "style".
While a completely custom "style" could be supplied, this library comes with several built-in "styles" that some people might find useful.
Following is the list of built-in "styles".
Rounds the time up to the closest time measurement unit (second, minute, hour, etc).
timeAgo.format(Date.now(), 'round')
// 0 seconds ago → "just now"
timeAgo.format(Date.now() - 15 * 1000, 'round')
// 15 seconds ago → "15 seconds ago"
timeAgo.format(Date.now() - 1.5 * 60 * 1000, 'round')
// 1.5 minutes ago → "2 minutes ago"
Same as "round" but without seconds.
timeAgo.format(Date.now(), 'round-minute')
// 0 seconds ago → "just now"
timeAgo.format(Date.now() - 15 * 1000, 'round-minute')
// 45 seconds ago → "just now"
timeAgo.format(Date.now() - 15 * 1000, 'round-minute')
// 46 seconds ago → "1 minute ago"
timeAgo.format(Date.now() - 1.5 * 60 * 1000, 'round-minute')
// 1.5 minutes ago → "2 minutes ago"
"approximate" style is a legacy one that has been introduced in the early versions of this library. It's basically the same as "round-minute" with the difference that it rounds time in some cases:
just now → just now40 seconds ago → just now45 seconds ago → 1 minute ago5 minutes ago → 5 minutes ago6 minutes ago → 5 minutes ago7 minutes ago → 5 minutes ago8 minutes ago → 10 minutes ago9 minutes ago → 10 minutes ago10 minutes ago → 10 minutes agotimeAgo.format(Date.now(), 'approximate')
// 0 seconds ago → "just now"
timeAgo.format(Date.now() - 15 * 1000, 'approximate')
// 15 seconds ago → "just now"
timeAgo.format(Date.now() - 1.5 * 60 * 1000, 'approximate')
// 1.5 minutes ago → "2 minutes ago"
timeAgo.format(Date.now() - 3 * 60 * 1000, 'approximate')
// 3 minutes ago → "5 minutes ago"
For historical reasons, "approximate" style is the one that's used when no style argument is passed (this will be changed in the next major version: round or round-minute will be the default one).
"approximate-time" style is a legacy one that has been introduced in the early versions of this library. It's the same as the "approximate" style but without the "ago" part.
timeAgo.format(Date.now(), 'approximate-time')
// 0 seconds ago → "just now"
timeAgo.format(Date.now() - 15 * 1000, 'approximate-time')
// 15 seconds ago → "just now"
timeAgo.format(Date.now() - 1.5 * 60 * 1000, 'approximate-time')
// 1.5 minutes ago → "2 minutes"
timeAgo.format(Date.now() - 3 * 60 * 1000, 'approximate-time')
// 3 minutes ago → "5 minutes"
Not all locales support this style: only those having long-time.json.
Mimics Twitter style of "time ago" labels ("1s", "2m", "3h", "Mar 4", "Apr 5, 2012")
timeAgo.format(new Date(), 'twitter')
// 0 seconds ago → "0s"
timeAgo.format(new Date() - 1, 'twitter')
// 1 second ago → "1s"
timeAgo.format(Date.now() - 1.5 * 60 * 1000, 'twitter')
// 1.5 minutes ago → "2m"
timeAgo.format(Date.now() - 3.5 * 60 * 60 * 1000, 'twitter')
// 3.5 hours ago → "4h"
timeAgo.format(Date.now() - 4 * 24 * 60 * 60 * 1000, 'twitter')
// More than 24 hours ago → `month/day` ("Mar 4")
timeAgo.format(Date.now() - 364 * 24 * 60 * 60 * 1000, 'twitter')
// Another year → `month/day/year` ("Mar 5, 2017")
"twitter" style uses Intl for formatting day/month/year labels. If Intl is not available (for example, in Internet Explorer), it falls back to day/month/year labels: "1d", "1mo", "1yr".
For best compatibility, mini-time.json labels should be defined for a locale. Send pull requests for the missing ones.
Same as "twitter" style but doesn't output anything before the first minute.
timeAgo.format(new Date(), 'twitter-first-minute')
// 0 seconds ago → ""
timeAgo.format(new Date() - 1, 'twitter-first-minute')
// 45 seconds ago → ""
timeAgo.format(new Date() - 1, 'twitter-first-minute')
// 46 seconds ago → "1m"
// The rest is same as "twitter" style.
"twitter-first-minute" style uses Intl for formatting day/month/year labels. If Intl is not available (for example, in Internet Explorer), it falls back to day/month/year labels: "1d", "1mo", "1yr".
For best compatibility, mini-time.json labels should be defined for a locale. Send pull requests for the missing ones.
A custom "style" object may be passed as a second parameter to .format(date, style), a style being an object defining labels and steps.
labels should be the name of the time labels variant that will be used for generating output. When not defined, is set to "long" by default.
labels can also be an array of such time label variant names, in which case each one of them is tried until a supported one is found. For example, for labels: ["mini-time", "short"] it will search for "mini-time" labels first and then fall back to "short" labels if "mini-time" labels aren't defined for the language.
"long", "short" and "narrow" time labels are always present for each language, because they're provided by CLDR. long is the normal one, short is an abbreviated version of long, narrow is supposed to be shorter than short but ends up just being weird: it's either equal to short or is, for example, "-1 d." for "1 day ago" in Russian.
Other time labels like "now" and "mini-time" are only defined for a small subset of languages. Send your pull requests for the missing ones.
New labels can be added by calling TimeAgo.addLabels() function.
import TimeAgo from 'javascript-time-ago'
import en from 'javascript-time-ago/locale/en'
import { round } from 'javascript-time-ago/locale/steps'
TimeAgo.addLocale(en)
const customLabels = {
second: {
past: {
one: "{0} second earlier",
other: "{0} seconds earlier"
},
future: {
one: "{0} second later",
other: "{0} seconds later"
}
},
...
}
TimeAgo.addLabels('en', 'custom', customLabels)
const timeAgo = new TimeAgo('en-US')
const customStyle = {
steps: round,
labels: 'custom'
}
timeAgo.format(Date.now() - 10 * 1000, customStyle)
// "10 seconds earlier"
Time interval measurement "steps".
Each "step" is tried until the last matching one is found, and that "step" is then used to generate the output. If no matching step was found, then an empty string is returned.
An example of "round" style steps:
[
{
// "second" labels are used for formatting the output.
formatAs: 'second'
},
{
// This step is effective starting from 59.5 seconds.
minTime: 59.5,
// "minute" labels are used for formatting the output.
formatAs: 'minute'
},
{
// This step is effective starting from 59.5 minutes.
minTime: 59.5 * 60,
// "hour" labels are used for formatting the output.
formatAs: 'hour'
},
…
]
A basic step is described by:
minTime: number — A minimum time interval (in seconds) required for this step, meaning that minTime controls the progression from one step to another. The first step's minTime is 0 by default.formatAs: string — A time measurement unit, the labels for which are used to generate the output of this step. If the time unit isn't supported by the language, then the step is ignored. The time units supported in all languages are: second, minute, hour, day, week, quarter, month, year. For some languages, this library also defines now unit ("just now").Alternatively to minTime, a step may specify a test() function:
test(
date: number, // The date argument, converted to a timestamp.
{
now: number, // The current date timestamp.
future: boolean // Is `true` if `date > now`, or if `date === now`
// and `future: true` option was passed to `.format()`.
}
): boolean
Alternatively to formatAs, a step may specify a format() function:
format(
date: (Date|number), // The date argument, as it has been passed to `.format()`:
// either a `Date` or a `number`.
// Converting it to `Date`:
// `date = typeof date === 'number' ? new Date(date) : date`
// Converting it to timestamp:
// `const timestamp = date.getTime ? date.getTime() : date`
locale: string, // The currently selected language. Example: "en".
{
formatAs(unit: string, value: number): string,
// A function that could be used to format `value` in `unit`s.
// Example: `formatAs('second', -2)`
// Outputs: "2 seconds ago"
now: number, // The current date timestamp.
future: boolean // Is `true` if `date > now`, or if `date === now`
// and `future: true` option was passed to `.format()`.
}
): string?
steps/steps export provides a couple of built-in "steps" that can be used when creating custom styles.
import { round, approximate } from 'javascript-time-ago/steps'
"approximate" — (legacy) The steps used in the "approximate" style.
/steps export provides some utility time unit constants that could be used to calculate minTime values when defining custom steps:
import { minute, hour, day, week, month, year } from 'javascript-time-ago/steps'
// In seconds
minute === 60
hour === 60 * 60
day === 24 * 60 * 60
...
const customSteps = [{
minTime: 5 * minute,
...
}]
When given future dates, .format() produces the corresponding output.
timeAgo.format(Date.now() + 5 * 60 * 1000, 'round')
// "in 5 minutes"
Zero time interval is a special case: by default, it's formatted in past time. To format zero time interval in future time, pass future: true option to .format().
// Without `future: true` option:
timeAgo.format(Date.now(), 'round')
// "just now"
timeAgo.format(Date.now() + 5 * 60 * 1000, 'round')
// "in 5 minutes"
// With `future: true` option:
timeAgo.format(Date.now(), 'round', { future: true })
// "in a moment"
timeAgo.format(Date.now() + 5 * 60 * 1000, 'round', { future: true })
// "in 5 minutes" (no difference)
The .format() function accepts an optional now: number option: it can be used in tests to specify the exact "base" timestamp relative to which the time interval will be calculated.
timeAgo.format(60 * 1000, 'round', { now: 0 })
// "1 minute ago"
When speaking of good User Experience ("UX"), a formatted relative date, once rendered, should be constantly refreshed. And for that, the application should know how often should it refresh the formatted date. For that, each step should provide an update interval.
When a step has formatAs configured, then getTimeToNextUpdate() function is created automatically for it. Otherwise, a developer should supply their own getTimeToNextUpdate() function for a step.
getTimeToNextUpdate(
date: (Date|number), // The date argument, as it has been passed to `.format()`:
// either a `Date` or a `number`.
// Converting it to `Date`:
// `date = typeof date === 'number' ? new Date(date) : date`
// Converting it to timestamp:
// `const timestamp = date.getTime ? date.getTime() : date`
{
getTimeToNextUpdateForUnit(unit: string): number,
// Returns "time to next update" for a time unit.
// This is what the library calls internally
// when `formatAs` is configured for a `step`.
// Example: `getTimeToNextUpdateForUnit('minute')`
now: number, // The current date timestamp.
future: boolean // Is `true` if `date > now`, or if `date === now`
// and `future: true` option was passed to `.format()`.
}
): number?
The application can then pass getTimeToNextUpdate: true option to .format() to get the best time to update the relative date label.
const timeAgo = new TimeAgo('en-US')
let output
let updateTimer
function render() {
const [formattedDate, timeToNextUpdate] = timeAgo.format(date, 'round', {
getTimeToNextUpdate: true
})
output = formattedDate
// The returned `timeToNextUpdate` may be `undefined`,
// so provide a sensible default.
updateTimer = setTimeout(render, timeToNextUpdate || 60 * 1000)
}
The "default locale" is the locale used when none of the locales passed to new TimeAgo() constructor are supported. By default, the "default locale" is "en".
TimeAgo.setDefaultLocale('ru')
This library uses an Intl.RelativeTimeFormat polyfill under the hood. The polyfill is only 3.5 kB in size so it won't affect the total bundle size.
Some people have
requested the ability to use native Intl.RelativeTimeFormat and Intl.PluralRules instead of the polyfills: in this case, pass polyfill: false option when creating a TimeAgo instance.
new TimeAgo('en-US', { polyfill: false })
There is also a React component built upon this library, that autorefreshes itself.
(this is an "advanced" section)
Intl global object is not required for this library, but, for example, if you choose to use the built-in twitter style then it will format longer intervals as 1d, 1mo, 1yr instead of Apr 10 or Apr 10, 2019 if Intl is not available: that's because it uses Intl.DateTimeFormat for formatting absolute dates.
Intl is present in all modern web browsers and is absent from some of the old ones: Internet Explorer 10, Safari 9 and iOS Safari 9.x (which can be solved using Intl polyfill).
Node.js starting from 0.12 has Intl built-in, but only includes English locale data by default. If your app needs to support more locales than English on server side (e.g. Server-Side Rendering) then you'll need to use Intl polyfill.
An example of applying Intl polyfill:
npm install intl@1.2.4 --save
Node.js
import IntlPolyfill from 'intl'
const locales = ['en', 'ru', ...]
if (typeof Intl === 'object') {
if (!Intl.DateTimeFormat || Intl.DateTimeFormat.supportedLocalesOf(locales).length !== locales.length) {
Intl.DateTimeFormat = IntlPolyfill.DateTimeFormat
}
} else {
global.Intl = IntlPolyfill
}
Web browser: only download intl package if the web browser doesn't support it, and only download the required locale.
async function initIntl() {
if (typeof Intl === 'object') {
return
}
await Promise.all([
import('intl'),
import('intl/locale-data/jsonp/en'),
import('intl/locale-data/jsonp/ru'),
...
])
}
initIntl().then(...)
FAQs
Localized relative date/time formatting
The npm package javascript-time-ago receives a total of 369,894 weekly downloads. As such, javascript-time-ago popularity was classified as popular.
We found that javascript-time-ago demonstrated a healthy version release cadence and project activity because the last version was released less than a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
A malicious npm package disguised as a WhatsApp client is exploiting authentication flows with a remote kill switch to exfiltrate data and destroy files.
Security News
PyPI now supports digital attestations, enhancing security and trust by allowing package maintainers to verify the authenticity of Python packages.
Security News
GitHub removed 27 malicious pull requests attempting to inject harmful code across multiple open source repositories, in another round of low-effort attacks.