jquery-timeago: fuzzy timestamps for pages that already run jQuery

What jquery-timeago actually replaces

A server can render "December 17, 2011" once, but that string is wrong the moment the page is a day old. jquery-timeago takes the machine-readable datetime already sitting in your HTML and rewrites the visible text into a relative phrase, then keeps rewriting it as time passes. The README describes the output as "automatically updating fuzzy timestamps (e.g. "4 minutes ago" or "about 1 day ago")".

The audience is narrow and specific: a page that already loads jQuery and already emits ISO 8601 timestamps, typically from a CMS, a Rails view or a hand-written template. If your dates only exist as pre-formatted strings with no datetime attribute, this plugin has nothing to read. The README's own example shows the required shape: a `<time>` element with a class of `timeago` and a `datetime` attribute in ISO 8601 form. That constraint is the whole integration.

How the plugin reads the DOM and keeps it current

The mechanism is a delegated scan. On DOM ready you select elements and call `.timeago()`, and the plugin reads each element's `datetime` attribute, compares it against the current time, and replaces the element's text with the fuzzy phrase. The README shows the before and after side by side: a `<time>` element carrying `datetime="2011-12-17T09:24:17Z"` and the text "December 17, 2011" becomes the same element with a `title` attribute set to the original text and the body text replaced with "about 1 day ago".

That title attribute is a deliberate trade: the precise value survives as a tooltip while the visible text stays fuzzy. The README also notes that `<abbr>` elements work, not just `<time>`, for legacy microformat support.

Updates are not driven by a server push. The plugin re-renders over time so the phrase stays accurate, and you can force a re-render yourself by calling the `update` method with a new ISO 8601 string or a `Date` object. That is the escape hatch for timestamps you insert after the initial scan, for example after an AJAX response.

Installing jquery-timeago and rendering your first timestamp

The README's usage section is written for a plain script tag: load jQuery, then load the plugin file, then attach on DOM ready. The npm package name is `timeago` and `package.json` points its `main` field at `jquery.timeago.js`.

A minimal HTML page following the README looks like this. The selector matches every element with the class, so you do not enumerate timestamps by hand.

<script src="jquery.min.js" type="text/javascript"></script>
<script src="jquery.timeago.js" type="text/javascript"></script>
<script type="text/javascript">
  jQuery(document).ready(function() {
    $("time.timeago").timeago();
  });
</script>

The markup each element needs is a class of `timeago` and an ISO 8601 `datetime` attribute. According to the README, after the plugin runs you should see the element's text replaced with a relative phrase and a `title` attribute holding the original string.

<time class="timeago" datetime="2011-12-17T09:24:17Z">December 17, 2011</time>

To refresh a timestamp you inserted later, call the update method with a new ISO 8601 string or a `Date`. Both forms appear in the README.

$("time#some_id").timeago("update", "2013-12-17T09:24:17Z");
// or
$("time#some_id").timeago("update", new Date());

The package is also published to Bower as `jquery-timeago`, and `package.json` declares a `browser` field mapping the `timeago` name to `./node_modules/timeago/jquery.timeago.js`. Non-English strings are not in the core file; the README points to the `locales` directory for "different language configurations", and the 1.6.x changelog entry says locales were wrapped in UMD wrappers.

The cutoff setting and the failure modes around it

Fuzzy phrasing degrades as distance grows. "about 3 years ago" is less useful than a date, and the plugin ships a setting for exactly that: `cutoff` returns the original date once the time distance exceeds a threshold in milliseconds. The README's example sets it to one day.

// Display original dates older than 24 hours
jQuery.timeago.settings.cutoff = 1000*60*60*24;

If you leave `cutoff` unset, every timestamp on the page is rewritten, including archived content from a decade ago. That is a real editorial decision, not a technical one, and the README does not push you toward either answer.

The harder failure mode is input. The plugin reads the `datetime` attribute and expects ISO 8601. Feed it a locale-formatted string, a timestamp missing its timezone, or an empty attribute, and there is no validation layer described in the README to catch it. The plugin also does nothing about timezone display: it compares against the client clock, so a reader whose system clock is wrong sees a wrong relative phrase, and the phrase is computed in the browser rather than the server's timezone.

Finally, jquery-timeago is the wrong tool if your dates are not in the DOM. If timestamps arrive as JSON from an API and are rendered by a component that never writes a datetime attribute, you are adding a plugin plus a rewrite of your templates to get what a date library would give you directly.

jquery-timeago versus date-fns

date-fns is the alternative that shows up in searches around this plugin, and the difference is architectural rather than cosmetic. date-fns is a date utility library: you import a function, pass it a Date object, and it returns a string. It has no opinion about your DOM, no jQuery dependency, and no automatic refresh. Rendering, re-rendering and attaching the result to an element are your responsibility.

jquery-timeago inverts that. It is a DOM plugin first: you give it a selector, it finds the elements, reads their attributes, and manages the update loop. The trade is that everything must already be in the markup in the right shape, and you take a jQuery dependency. `package.json` declares exactly one dependency, `jquery` at `>=1.5.0 <4.0`, which is a wide range and includes jQuery 1.x, 2.x and 3.x.

So the choice is not which library formats dates better. It is whether you want a self-managing DOM widget or a pure function you call from your own render path. A project on React, Vue or Svelte with no jQuery has little reason to add jQuery to get relative timestamps; a server-rendered jQuery page has little reason to hand-roll an update loop.

Release cadence, licence and what an upgrade costs

The most recent release listed is v1.6.7 from 2019-04-23, with v1.6.6 and v1.6.5 earlier that year. The repository is not archived, and the last push was on 2026-08-02, so commits are still landing, but the release history says the published artifact has been stable for years rather than moving quickly. Plan for a dependency that changes rarely.

That stability cuts both ways. There is no migration treadmill, and the 1.6.x changelog entry is limited to UMD-wrapped locales and locale improvements. There is also no evidence in the README of a deprecation path or a documented rollback procedure; the README does not document rollback. If a locale file's wording is wrong for your audience, your options are to edit the locale or override it, and the changelog entry for 0.7.x mentions "locale function overrides" as an earlier feature.

The licence is MIT, declared in `package.json` under a `licenses` array with the type `MIT` and a link to the MIT licence text, and the README's License section points to the same. MIT is permissive: it allows commercial use and modification with the copyright notice retained. That is the extent of what the repository states, and it is not legal advice for your particular distribution.

Editorial conclusion

Adopt jquery-timeago if you already load jQuery and your timestamps live in the DOM as datetime or title attributes; the plugin binds to those elements and needs no build step. Do not adopt it if you are on a modern framework without jQuery, or if you need date parsing, arithmetic or formatting beyond the relative string, since the package.json declares jquery >=1.5.0 <4.0 as its only dependency. Before rolling it out, verify that a non-English locale file exists for each language you ship, that your markup uses valid ISO 8601, and whether your timestamps are old enough that the cutoff setting should return the original date instead.

Frequently asked questions

Official sources

1. License: MIT
2. Project website
3. README
4. Releases
5. rmm5t/jquery-timeago on GitHub