Livestamp.js

A simple, unobtrusive jQuery plugin that provides auto-updating timeago text to your timestamped HTML elements using Moment.js.

What does it do?

<span data-livestamp=""></span>
<span></span>

The livestamp will update automatically as time goes by. ISO 8601 timestamps are also supported.

How is it used?

First thing's first: download the dependencies. You'll need jQuery (>= 1.7) and Moment.js (>= 1.7). Once you've got everything, put this somewhere in your page:

<script src="jquery.js"></script>
<script src="moment.js"></script>
<script src="livestamp.js"></script>

No extra JavaScript required! Just use a <span> with the data-livestamp attribute set to the desired Unix timestamp (in seconds), like this:

You discovered Livestamp.js <span data-livestamp=""></span>.

And you will see this:

You discovered Livestamp.js .

Wait half a minute — the livestamp will update automatically!


ISO 8601 timestamps are also supported in the data-livestamp attribute. This makes Livestamp.js compatible with other timeago plugins like jQuery timeago and Smart Time Ago. Just use an ISO 8601 string, like this:

Livestamp.js was first released
<span data-livestamp="2012-08-03T00:29:22-07:00"></span>.

And it will report this:

Livestamp.js was first released .

By the way, you can use any element you want. Just make sure the data-livestamp attribute has a valid timestamp. The <abbr> element is a good choice. For instance:

Not even <abbr title="" data-livestamp=""></abbr>,
you were still looking for the perfect jQuery timeago plugin.

Will assume this:

Not even , you were still looking for the perfect jQuery timeago plugin.

You can even use timestamps in the future! This works well for fortune-tellers, time travelers, and meteorologists. Just don't go too far into the future (or the past for that matter).

You will start using Livestamp.js in your own project
<span data-livestamp=""></span>.

Will predict this:

You will start using Livestamp.js in your own project .

Afraid of unobtrusive JavaScript? No sweat: you can livestamp your elements manually using jQuery. The $(…).livestamp() function accepts a Date object, a Moment object, or a Number timestamp.

Matt Bradley was born <span id="birth">on June 18, 1987</span>.
<script>
function livestampBirthday() {
$('#birth').livestamp(new Date('June 18, 1987'));
}
</script>

Use the buttons to try it out:

Matt Bradley was born on June 18, 1987.

Use $(…).livestamp('destroy') to remove all livestamp data and restore the element's original HTML.


Livestamped elements will let you know before they change; they're just thoughtful like that. Subscribe to the change.livestamp event: it's triggered right before the text is changed. Use this to implement stuff like custom animations:

This fade-in-fade-out animation started <span id="animation"></span>.
<script>
$('#animation').on('change.livestamp', function(event, from, to) {
event.preventDefault(); // Stop the text from changing automatically
$(this).fadeOut(function() {
$(this).html(to).fadeIn();
});
}).livestamp();
</script>

Will create this custom change animation:

This fade-in-fade-out animation started .

How can I get it?

Click one of the buttons above to get Livestamp.js. The full source and previous versions can be found at the Livestamp.js GitHub repository.

I'm using it on my site!

Great! Tell me about it @mattbradley!

Is it free?

Of course! Livestamp.js is freely distributable under the MIT License, which means you can pretty much do anything you want with it as long as you keep my copyright on the source code.

Is it buggy?

Hell no! Check out the unit tests to run the test suite in your browser.

What about suggestions?

I guess those are okay, but come on! You're a programmer for cryin' out loud! Fork the repo and make a contribution to society by implementing it yourself.

What is Moment.js?

Only the most awesome JavaScript date library. Livestamp.js uses Moment's formatting methods to generate the timeago text. It has a lot of other great features, too. Check it out!

¡No hablo inglés!

¡No hay problema! Since Livestamp.js uses Moment.js to generate all of the text, it also includes Moment's language support. Check out its i18n docs for info on using other languages.

Why not milliseconds?

So, you want to know why the timestamp has to be in seconds instead of milliseconds? Yes, I know that JavaScript usually handles timestamps in milliseconds (e.g., the new Date() constructor). But there's a couple of reasons why I chose to handle timestamps in seconds instead:

  1. A lot of server-side scripting languages (PHP, Ruby, Perl, Python, etc.) handle timestamps in seconds. This makes it easy to print out a timestamp into HTML. In Ruby, for instance:

    <span
     data-livestamp="<%= Time.now.to_i %>">
    </span>

  2. Some server-side languages only use 32-bit integers. For example, PHP (when running on a 32-bit machine) can only manage integers up to 2,147,483,647 (231 − 1). Anything higher is cast to a float. PHP handles timestamps in seconds, so, if Livestamp.js used milliseconds instead of seconds, any timestamp being printed would have to be multiplied by 1,000 first. This means most millisecond Unix timestamps would be cast to floats. Since floats are approximate data-structures, you might not get the correct integer timestamp when printing it out (it might even be on a different day if it's close to midnight). By using seconds instead of milliseconds, the timestamps can be exact integers (at least until they overflow).

    If you must have millisecond precision, try this:

    <span data-livestamp=""></span>