Localized relative date/time formatting
Date into a string like "1 day ago". In any language.
npm install javascript-time-ago --save
`
Alternatively, one could include it on a web page directly via a tag.
Use
To begin, decide on the set of languages that your application will be translated into. For now, let's assume that it's gonna be just English.
Then, for each of those languages, import the language data from javascript-time-ago/locale/.., and pass it to TimeAgo.addLocale() function.
`js
import TimeAgo from 'javascript-time-ago'
import en from 'javascript-time-ago/locale/en'
// Add English language
TimeAgo.addLocale(en)
`
Now you're ready to create a new TimeAgo() formatter for any of those languages, and use it to convert dates into strings.
`js
// Create English formatter
const timeAgo = new TimeAgo('en')
timeAgo.format(new Date())
// "just now"
timeAgo.format(Date.now() - 60 * 1000)
// "1 minute ago"
timeAgo.format(Date.now() - 2 60 60 * 1000)
// "2 hours ago"
timeAgo.format(Date.now() - 24 60 60 * 1000)
// "1 day ago"
`
To change the output style, see the list of available formatting styles.
P.S. After rendering a label, don't forget to refresh it as the time goes by.
Languages
This library supports a lot of languages. None of those languages are loaded by default. A developer must manually choose which languages should be loaded and then call TimeAgo.addLocale() for each one of them.
The locale argument of new TimeAgo(locale) constructor will be matched against the list of added languages, and the first matching one will be used. For example, new TimeAgo("en") and new TimeAgo("en-US") will both use "en" language.
If the language for the specified locale hasn't been added, it will retry with a "default" locale. For that, a "default" locale has to have been added by calling TimeAgo.addDefaultLocale(). Otherwise, when there's no "default" locale to fall back to, it will just throw an error.
So how is "default" locale useful? It frees a developer from worrying about whether the locale argument is supported or not. They can just create a new TimeAgo() formatter with whatever locale argument and not even worry about potentially crashing the application in case it throws an error for that locale.
In the following example, the application supports three languages — English, German and French — and English is set to be the "default" one that will be used for any other language like Spanish.
`js
import en from 'javascript-time-ago/locale/en'
import de from 'javascript-time-ago/locale/de'
import fr from 'javascript-time-ago/locale/fr'
TimeAgo.addDefaultLocale(en)
TimeAgo.addLocale(de)
TimeAgo.addLocale(fr)
`
`js
// "es" locale hasn't been added, so it falls back to "en".
const timeAgo = new TimeAgo('es')
timeAgo.format(new Date())
// "just now"
`
TimeAgo.addDefaultLocale() is just a shortcut for TimeAgo.addLocale() + TimeAgo.setDefaultLocale(), so the code above is the same as the code below.
`js
import en from 'javascript-time-ago/locale/en'
import de from 'javascript-time-ago/locale/de'
import fr from 'javascript-time-ago/locale/fr'
TimeAgo.addLocale(en)
TimeAgo.addLocale(de)
TimeAgo.addLocale(fr)
TimeAgo.setDefaultLocale('en')
`
new TimeAgo() constructor also supports passing a list of locales to choose from. In that case, it will choose the first one that works.
`js
// Add English and German languages
TimeAgo.addDefaultLocale(en)
TimeAgo.addLocale(de)
// "de" language will be chosen because it's the first one that works.
const timeAgo = new TimeAgo(['ru-RU', 'de-DE', 'en-US'])
timeAgo.format(new Date())
// "gerade jetzt"
`
Formatting Styles
A "formatting style" defines how a date should be formatted relative to the current time.
It could be precise up to a second with "1 second ago", "2 seconds ago", "3 seconds ago", etc labels, or it could prefer to combine all those under a single "less than a minute ago" label.
It could use verbose labels like "1 minute ago" or it could prefer shorter variants like "1 min. ago" or even "1m". Or it could prefer to output a full date like "Dec 11, 2015" for dates that're older than 1 year from now.
While one could certainly implement their own custom formatting "style" from scratch, most applications would be totally fine with one of the few already-available styles that're described below.
$3
"round" style just rounds the time difference up to the closest unit of time — second, minute, hour, etc — and then returns a label for that unit of time.
`js
timeAgo.format(Date.now(), 'round')
// 0 seconds ago: "just now"
timeAgo.format(Date.now() - 1 * 1000, 'round')
// 1 second ago: "1 second ago"
timeAgo.format(Date.now() - 29 * 1000, 'round')
// 29 seconds ago: "29 seconds ago"
timeAgo.format(Date.now() - 30 * 1000, 'round')
// 30 seconds ago: "1 minute ago"
timeAgo.format(Date.now() - 1.5 60 1000, 'round')
// 1.5 minutes ago: "2 minutes ago"
`
* just now
* 1 second ago
* 2 seconds ago
* …
* 59 seconds ago
* 1 minute ago
* 2 minutes ago
* …
* 59 minutes ago
* 1 hour ago
* 2 hours ago
* …
* 23 hours ago
* 1 day ago
* 2 days ago
* …
* 6 days ago
* 1 week ago
* 2 weeks ago
* 3 weeks ago
* 1 month ago
* 2 months ago
* …
* 11 months ago
* 1 year ago
* 2 years ago
* …
$3
"round-minute" style is same as "round" style but without seconds. This is the default style that is used when no custom style is specified.
`js
timeAgo.format(Date.now(), 'round-minute')
// 0 seconds ago: "just now"
timeAgo.format(Date.now() - 29 * 1000, 'round-minute')
// 29 seconds ago: "just now"
timeAgo.format(Date.now() - 30 * 1000, 'round-minute')
// 30 seconds ago: "1 minute ago"
// The rest is same as "round" style.
`
* just now
* 1 minute ago
* 2 minutes ago
* …
$3
"mini" style is same as "round" style but with labels that're as short as possible, without the " ago" part, and it doesn't output "weeks".
`js
timeAgo.format(new Date(), 'mini')
// 0 seconds ago: "0s"
timeAgo.format(new Date() - 1 * 1000, 'mini')
// 1 second ago: "1s"
timeAgo.format(Date.now() - 2 60 1000, 'mini')
// 2 minutes ago: "2m"
timeAgo.format(Date.now() - 3 60 60 * 1000, 'mini')
// 3 hours ago: "3h"
timeAgo.format(Date.now() - 4 24 60 60 1000, 'mini')
// 4 days ago: "4d"
timeAgo.format(Date.now() - 23 24 60 60 1000, 'mini')
// 23 days ago: "23d"
timeAgo.format(Date.now() - 5 30 24 60 60 * 1000, 'mini')
// 5 months ago: "5mo"
timeAgo.format(Date.now() - 12 30 24 60 60 * 1000, 'mini')
// 1 year ago: "1yr"
`
For best compatibility, mini.json labels should be defined for a locale, otherwise you might end up with labels like "-1m" for "one minute ago" for some languages. Send mini.json pull requests for the missing languages if you speak those.
$3
"mini-now" style is same as "mini" style with the only difference that it outputs "now" instead of "0s".
`js
timeAgo.format(new Date(), 'mini-now')
// 0 seconds ago: "now"
timeAgo.format(new Date() - 1 * 1000, 'mini-now')
// 1 second ago: "1s"
// The rest is same as "mini" style.
`
$3
"mini-minute" style is same as "mini" style but without seconds.
`js
timeAgo.format(new Date(), 'mini-minute')
// 0 seconds ago: "0m"
timeAgo.format(new Date() - 29 * 1000, 'mini-minute')
// 29 seconds ago: "0m"
timeAgo.format(new Date() - 30 * 1000, 'mini-minute')
// 30 seconds ago: "1m"
// The rest is same as "mini" style.
`
$3
"mini-minute-now" style is same as "mini-minute" style with the only difference that it outputs "now" instead of "0m".
`js
timeAgo.format(new Date(), 'mini-minute-now')
// 0 seconds ago: "now"
timeAgo.format(new Date() - 29 * 1000, 'mini-minute-now')
// 29 seconds ago: "now"
timeAgo.format(new Date() - 30 * 1000, 'mini-minute-now')
// 30 seconds ago: "1m"
// The rest is same as "mini" style.
`
$3
"twitter" style mimicks Twitter labels: "1s", "2m", "3h", "Mar 4", "Apr 5, 2012".
`js
timeAgo.format(new Date(), 'twitter')
// 0 seconds ago: "0s"
timeAgo.format(new Date() - 1 * 1000, 'twitter')
// 1 second ago: "1s"
timeAgo.format(Date.now() - 2 60 1000, 'twitter')
// 2 minutes ago: "2m"
timeAgo.format(Date.now() - 3 60 60 * 1000, 'twitter')
// 3 hours ago: "3h"
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.DateTimeFormat when formatting day/month/year labels. When Intl is not available — for example, in Internet Explorer — it falls back to the usual short labels: "1d", "1mo", "1yr", etc.
For best compatibility, mini.json labels should be defined for a locale. Send mini.json pull requests for the missing languages if you speak those.
$3
"twitter-now" style is same as "twitter" style with the only difference that it outputs "now" instead of "0s".
`js
timeAgo.format(new Date(), 'twitter-now')
// 0 seconds ago: "now"
timeAgo.format(new Date() - 1 * 1000, 'twitter-now')
// 1 second ago: "1s"
// The rest is same as "twitter" style.
`
$3
"twitter-minute" style is same as "twitter" style but without seconds.
`js
timeAgo.format(new Date(), 'twitter-minute')
// 0 seconds ago: "0m"
timeAgo.format(new Date() - 29 * 1000, 'twitter-minute')
// 29 seconds ago: "0m"
timeAgo.format(new Date() - 30 * 1000, 'twitter-minute')
// 30 seconds ago: "1m"
// The rest is same as "twitter" style.
`
$3
"twitter-minute-now" style is same as "twitter-minute" style with the only difference that it outputs "now" instead of "0m".
`js
timeAgo.format(new Date(), 'twitter-minute-now')
// 0 seconds ago: "now"
timeAgo.format(new Date() - 29 * 1000, 'twitter-minute-now')
// 29 seconds ago: "now"
timeAgo.format(new Date() - 30 * 1000, 'twitter-minute-now')
// 30 seconds ago: "1m"
// The rest is same as "twitter" style.
`
$3
"twitter-first-minute" style is same as "twitter" style with the only difference that it doesn't output anything before the first minute.
`js
timeAgo.format(new Date(), 'twitter-first-minute')
// 0 seconds ago: ""
timeAgo.format(new Date() - 29 * 1000, 'twitter-first-minute')
// 29 seconds ago: ""
timeAgo.format(new Date() - 30 * 1000, 'twitter-first-minute')
// 30 seconds ago: "1m"
// The rest is same as "twitter" style.
`
Custom Style
A custom "style" object may be passed as a second argument to .format(date, style) function. A style object should have two properties: labels and steps.
Refer to the definition of the built-in styles for an example.
How does a formatting style work
######
The time range (in seconds) spans from -∞ to +∞, with "now" at 0 point. This entire range gets split into intervals, each with its own label. Example:
* Interval from 0 to -1 second is assigned "just now" label.
* Interval from -1 second to -1 minute is assigned "{0} second(s) ago" label.
* Interval from -1 minute to -1 hour is assigned "{0} minute(s) ago" label.
* ...
* Interval from 0 to +1 second is assigned "in a moment" label.
* Interval from +1 second to +1 minute is assigned "in {0} second(s)" label.
* Interval from +1 minute to +1 hour is assigned "in {0} minute(s)" label.
* ...
Intervals follow each other without any gaps, so the entire time range is divided into such intervals.
Now the job of the format(date) function is simple: it calculates the time difference (in seconds) between date and "now", and then maps that number onto the time range to see what interval it falls into. Then it returns the label for that interval, replacing {0} with the time difference number converted to the unit of time used by the interval.
For example, for const date = new Date(Date.now() - 2 60 1000), format(date) first calculates the difference between the date and Date.now(), which is -2 60 seconds, and then maps those -2 60 seconds onto the time range and finds that it falls into the -1 min … -1 hour interval. So it returns the label for that interval, which is "{0} minute(s) ago", replacing {0} with 2 because the unit of time used by the interval is "minute" which is equal to 60 seconds, so -2 * 60 / 60 === -2.
As one can see, with this approach, there could be an infinite amount of all kinds of formatting styles, and any possible formatting style could be expressed with this simple logic.
$3
labels property value should be the type of labels to output. There're several types of labels available:
* Labels that're provided by Unicode CLDR for all languages:
* long labels are the "normal" ones. Example: "1 minute ago".
* short labels are an abbreviated version of long ones. Example: "1 min. ago".
* narrow labels are supposed to be shorter than short ones but for some reason they look fine for some languages and weird for other ones. For example, a short label for "1 day ago" is "1d ago" in English, which looks fine, and "-1 d." in Russian, which looks weird. So I personally don't use narrow labels.
* Labels that're provided by the community via pull requests, available for a subset of languages. If your language is missing from the list, you could create a pull request for it.
* mini labels are the shortest. Example: "1m".
* now labels describe the time interval between -1 second and +1 second. There're 3 labels total: one for -0.5 sec, one for 0 sec, and one for 0.5 sec. Example: "just now", "now", "in a moment".
The default value for the labels property is "long".
labels can also be an array of label types, in which case the first supported label type will be used. For example, for labels: ["mini", "short"] it will search for "mini" labels first and then fall back to "short" labels if "mini" labels aren't defined for the language. This could be useful when defining a "style" with labels that might not be defined for all languages.
One could also supply custom labels. To do that, define past and future labels for each unit of time — second, minute, hour, day, week, month, quarter, year — and then pass the object to TimeAgo.addLabels() function.
`js
import TimeAgo from 'javascript-time-ago'
import en from 'javascript-time-ago/locale/en'
// Steps from the built-in "round" style can be reused in custom styles.
import { round } from 'javascript-time-ago/steps'
TimeAgo.addLocale(en)
// Define custom labels.
const customLabels = {
second: {
past: {
one: "{0} second earlier",
other: "{0} seconds earlier"
},
future: {
one: "{0} second later",
other: "{0} seconds later"
}
},
...
}
// Add the custom labels for English language under "custom" name.
TimeAgo.addLabels('en', 'custom', customLabels)
// Create English formatter.
const timeAgo = new TimeAgo('en-US')
// Define a custom style that reuses the steps from the built-in "round" style
// and uses the newly added "custom" labels.
const customStyle = {
steps: round,
labels: 'custom'
}
// Format a "10 seconds ago" date using the new custom style.
timeAgo.format(Date.now() - 10 * 1000, customStyle)
// Returns "10 seconds earlier"
`
$3
steps property should define a set of intervals that cover the time difference from 0 to ±∞.
The .format() function starts at the first step and then moves to next one as long as the time difference passes the minTime threshold of the next step. The process is repeated until it stops at a certain step. That step is used to output the label.
If the .format() function doesn't pass the minTime threshold of the first step then it just outputs an empty string.
Here's an example of steps that're used in the built-in "round" style:
`js
[
{
// Starting from the time difference 0,
// use "second" labels.
formatAs: 'second'
},
{
// When the time difference becomes at least 1 minute (after rounding),
// use "minute" labels.
formatAs: 'minute'
},
{
// When the time difference becomes at least 1 hour (after rounding),
// use "hour" labels.
formatAs: 'hour'
},
…
]
`
Each "step" could be described by the following properties:
* formatAs?: string — The labels for which unit of time to use in the output: "second", "minute", etc.
* format?: (date) => string? — If a developer doesn't like to use the standard formatAs labels, they could output any custom label for a given date.
* minTime?: number — The minimum time difference (in seconds) required for the step. When not specified, will be derived from formatAs property — for example, formatAs: "minute" → minTime: 60 with round: "floor".
More on minTime
######
minTime threshold is the minimum time difference (in seconds) required for the step. Basically, minTime controls the progression from one step to another: it can't progress to the next step until the time difference (in seconds) reaches the minTime of that step.
Every step has to specify minTime, either explicitly or implicitly. An example of "implicitly" would be the first step's minTime which is 0 by default.
Another example of "implicitly" would be under-the-hood calcuation of minTime based on the unit of time of the step: when a step specifies formatAs property, and the previous step also specifies formatAs property, then the step's minTime, when not explicitly specified, is calculated automatically from those formatAs properties according to the selected "rounding". For example, if the previous step is { formatAs: "second" } and the current step is { formatAs: "minute" } then the current step's minTime is automatically calculated to be 59.5 when round is set to "round" (default), or 60 when round is set to "floor".
So in almost all cases, the library automatically calculates minTime for you. However, if you're implementing some kind of an extravagant custom "style" then for steps that don't specify formatAs property you will be required to specify minTime explicitly.
In that case, even though minTime could be specified as a number, the recommended way is to specify it as a function returning a number because that would be the only way to account for the rounding setting, which, by default, is "round", but could also be "floor".
* minTime() — Returns the minTime number.
* Arguments:
* date: number — The date, converted to a timestamp number. Not a time difference.
* parameters: object
* future: boolean — Is true either when date > now or when date === now and future: true parameter was passed to .format().
* getMinTimeForUnit(unit: string, prevUnit?: string): number? — returns the minimum time difference (in seconds) required for moving from a step with formatAs: prevUnit to a step with formatAs: unit.
* Example:
* When round is set to "round" (default), getMinTimeForUnit("minute", "second") returns 59.5, meaning that the minimum time difference for moving from "second" labels to "minute" labels is 59.5 seconds, and for smaller time differences it should stay at "second" labels.
* When round is set to "foor", getMinTimeForUnit("minute", "second") returns 60, meaning that the minimum time difference for moving from "second" labels to "minute" labels is 60 seconds, and for smaller time differences it should stay at "second" labels.
* The second argument — prevUnit — is not required and will be automatically set to the previous step's formatAs property value.
* If unit or prevUnit argument is invalid, getMinTimeForUnit() will not throw an error and will just return undefined.
More on formatAs
######
formatAs is the unit of time, the labels for which will be used to generate the output of the step. If the specified unit of time isn't supported by the language (as explained further), then such step is ignored. The units of time that're supported in all languages are: second, minute, hour, day, week, month, quarter, year. For some languages, this library defines an additional unit called now which can be used to output labels like "just now". So if a step specifies formatAs: "now" and now unit isn't supported in a given language then such step is just skipped. If your language doesn't have a now.json, send a pull request (native speakers only).
More on format()
######
A developer might prefer to output a custom label for a given step. In that case, instead of specifying formatAs property, they should specify a format() function.
* format() — Returns a custom label, or undefined for an empty output.
* Arguments:
* date: number — The date, converted to a timestamp number. Not a time difference.
* locale: string — The selected language. Example: "en".
* parameters: object
* formatAs(unit: string, amount: number): string — A function that can be used to get a label for an amount of given units of time.
* Example: formatAs('second', -2) returns "2 seconds ago".
* now: number — The current date's timestamp. Use it instead of Date.now() to avoid the issue of Date.now() being slightly different for each different step.
* future: boolean — Is true either when date > now or when date === now and future: true parameter was passed to .format().
Refreshing
After a time label has been rendered, it should periodically be updated (refreshed), because the label will change as the time flows. For that, the application needs to know how often it should refresh the label. It could refresh the label every second but that wouldn't be very efficient. For example, there's absolutely no need to refresh a "1 year ago" label every second. So how does one know how soon should the label be refreshed?
This library provides an easy way to know when is the best time to refresh the label:
`js
const [text, refreshDelay] = timeAgo.format(date, { getTimeToNextUpdate: true })
`
Example:
`js
let timerId
function renderLoop() {
const [text, refreshDelay] = timeAgo.format(date, { getTimeToNextUpdate: true })
// Update the label text.
timeLabel.textContent = text
if (refreshDelay !== undefined) {
timerId = setTimeout(renderLoop, refreshDelay)
}
}
// Render the label.
// It will automatically be refreshed when needed
timeLabel = createTimeLabelElement()
renderLoop()
// And when the label is no longer rendered, one should manually stop the periodic refresh.
clearTimeout(timerId)
`
The code above could be simplified by passing a refresh function instead of getTimeToNextUpdate: true parameter:
`js
const [text, stopRefreshing] = timeAgo.format(date, {
// It will automatically call the refresh() function every time the label needs to be refreshed.
refresh: (text) => {
// Update the label text.
timeLabel.textContent = text
}
})
// Render the label.
// It will automatically be refreshed when needed.
timeLabel = createTimeLabelElement()
timeLabel.textContent = text
// And when the label is no longer rendered, one should manually stop the periodic refresh.
stopRefreshing()
`
If you're only using the built-in "styles", the returned timeToNextUpdate number is always defined. If you're using a custom "style", it is possible that it doesn't support timeToNextUpdate feature "out of the box" and in that case the returned timeToNextUpdate could be undefined. So as a general rule, when using a custom "style", always check that timeToNextUpdate is not undefined, and if it is, then assign some default refresh interval to it — like one minute (60 * 1000).
See the conditions that a custom formatting "style" has to meet in order to work well with getTimeToNextUpdate: true feature
* When each step in a given formatting "style" specifies a minTime, timeToNextUpdate can easily be calcuated by subtracting the current time difference from the minTime threshold of the next step.
* For steps that don't explicitly specify minTime, minTime can still be derived from formatAs property.
* For steps that don't specify niether minTime nor formatAs property, the calculation of timeToNextUpdate becomes slightly more complicated: such steps are required to specify a getTimeToNextUpdate() function property.
* getTimeToNextUpdate()
* Returns:
* timeToNextUpdate: number? — The time until next update. If it returns undefined then it's interpreted as "the current label is constant and will not change" — for example, "Jan 1, 2000".
* Arguments:
* date: number — The date, converted to a timestamp number. Not a time difference.
* parameters: object
getTimeToNextUpdateForUnit(unit: string): number — A function that returns the "time until next update" (in milliseconds) for a given unit of time. For example, when using the default rounding method, and the argument is "minute", and the current time difference is 60 1000 milliseconds, then the current label is gonna be "1 minute ago" and the "time until next update" for that label will be 30 * 1000 milliseconds because that's the time after which "1 minute ago" label changes into "2 minutes ago".
* The library itself uses this function when calculating the "time until next update" for steps that don't specify minTime but do specify formatAs property.
* getTimeToNextUpdateForUnit("now") always returns undefined.
* The return value of the function depends on the exact time that it was called at, i.e. when called at different times, it will produce different results. Example:
* Consider that the current time difference is -20 seconds and the unit of time is "minute".
* Initially, it outputs "0 minutes ago" because it rounds 20/60 to 0.
* What will getTimeToNextUpdateForUnit("minute") return?
When round value is "round" (default), it will return 10 1000 milliseconds, because 20 + 10 = 30, and 30 seconds of time difference is the moment when it rounds 0.5 minute to 1 minute and changes the label from "0 minutes ago" to "1 minute ago".
When round value is "floor", it will return 40 1000 milliseconds, because 20 + 40 = 60, and 60 seconds of time difference is the moment when it rounds 1.0 minute to 1 minute and changes the label from "0 minutes ago" to "1 minute ago".
* Now imagine that 20 seconds have passed. What will getTimeToNextUpdateForUnit("minute") return now?
When round value is "round" (default), it will return 50 1000 milliseconds, because 20 + 20 + 50 = 90, and 90 seconds of time difference is the moment when it rounds 1.5 minute to 2 minutes and changes the label from "1 minute ago" to "2 minutes ago".
When round value is "floor", it will return 20 1000 milliseconds, because 20 + 20 + 20 = 60, and 60 seconds of time difference is the moment when it rounds 1.0 minute to 1 minute and changes the label from "0 minutes ago" to "1 minute ago".
* As the time goes by, getTimeToNextUpdateForUnit("minute") will keep returning a different result every other time it is called.
* now: number — The current date's timestamp. Use it instead of Date.now() to avoid the issue of Date.now() being slightly different for each different step.
* future: boolean — Is true either when date > now or when date === now and future: true parameter was passed to .format().
Rounding
When printing a label such as "1 minute ago", the time difference number has to be rounded for readability. For example, it won't print "0.49 minutes ago". It has to round that number first.
The round setting controls how exactly fractional numbers should be rounded to integers.
The default round setting is "round" which follows Math.round() behavior.
* 0.1 sec. ago → "0 sec. ago"
* 0.4 sec. ago → "0 sec. ago"
* 0.5 sec. ago → "1 sec. ago"
* 0.9 sec. ago → "1 sec. ago"
* 1.0 sec. ago → "1 sec. ago"
Some people asked for an alternative rounding method, so there's an alternative round setting value "floor" which follows Math.floor() behavior.
* 0.1 sec. ago → "0 sec. ago"
* 0.4 sec. ago → "0 sec. ago"
* 0.5 sec. ago → "0 sec. ago"
* 0.9 sec. ago → "0 sec. ago"
* 1.0 sec. ago → "1 sec. ago"
A developer can specify the preferred rounding by passing a round parameter to timeAgo.format(date, [style,] options).
The default rounding method could also be specified "globally" for a given style by specifying a round property in the style object.
Past vs Future
When given a past date, .format() returns an "... ago" label.
When given a future date, .format() returns an "in ..." label.
`js
timeAgo.format(Date.now() + 5 60 1000)
// "in 5 minutes"
`
When given a "now" date, which is neither past, nor future, .format() doesn't really know how it should represent the time difference — as -0 or as +0.
By default, it treats it as -0, meaning that it will return "0 seconds ago" rather than "in 0 seconds".
To instruct .format() to treat it as +0, pass future: true parameter.
`js
// Without future: true
timeAgo.format(Date.now())
// "just now"
// With future: true
timeAgo.format(Date.now(), { future: true })
// "in a moment"
`
now parameter
The .format() function accepts an optional now: number parameter. It is used in tests to specify the exact "base" timestamp relative to which the time difference will be calculated.
`js
timeAgo.format(60 * 1000, { now: 0 })
// "1 minute ago"
`
Full Date Formatter
Usually, when rendering a "relative" time label, one should also provide an "absolute" time label, perhaps somewhere in a tooltip, for the user to be able to know the precise date/time of the event.
This library exports a "helper" date formatter for just that:
`js
import FullDateFormatter from 'javascript-time-ago/full-date-formatter'
const formatter = new FullDateFormatter('en')
const tooltipText = formatter.format(date)
// Example output: "Saturday, January 1, 2000 at 3:00:00 AM"
`
FullDateFormatter uses Intl.DateTimeFormat under the hood, which works in all modern browsers, and falls back to Date.toString() for ancient web browsers like Internet Explorer.
React
For React users, there's a React version of this library. See demo.
Intl.RelativeTimeFormat Polyfill
This library uses an Intl.RelativeTimeFormat polyfill under the hood. That polyfill is only 3.5 kB in size so it won't affect the total bundle size.
Still, some people have
requested the ability to use native Intl.RelativeTimeFormat and Intl.PluralRules instead of the polyfills. To do that, pass polyfill: false option when creating a TimeAgo instance.
`js
new TimeAgo('en-US', { polyfill: false })
`
CDN
To include this library directly via a tag on a page, one can use any npm CDN service, e.g. unpkg.com or jsdelivr.com
`html
`
Tests
This component comes with a 100% code coverage.
To run tests:
`
npm test
`
To generate a code coverage report:
`
npm run test-coverage
`
The code coverage report can be viewed by opening ./coverage/lcov-report/index.html.
Previously, when generating a code coverage report, it used to print a cryptic error message in the console and then produce an empty code coverage report:
`
Handlebars: Access has been denied to resolve the property "statements" because it is not an "own property" of its parent.
You can add a runtime option to disable the check or this warning:
See https://handlebarsjs.com/api-reference/runtime-options.html#options-to-control-prototype-access for details
`
That has been worked around by "anchoring" handlebars version in devDependencies at handlebars@4.5.3`.