Fork me on GitHub

Sensible DateTime

Sensible DateTime is a jQuery plugin that makes it easy to format ISO datetime into something sensible as you see fit.


There are a handful of Javascript libraries that convert date on your page to relative time or format them. However, they are usually set in their predefined way.

Sensible DateTime provides more flexibility that helps display date and time on the website according to your specific needs and context.



<p>You opened this page <abbr class="datetime opened">opened time</abbr>.<!-- dynamically generated --></p>
<p>Someone posted something <time class="datetime" datetime="2011-09-27T15:40:00">2011, Sep 27th</time></p>
<p>John shared his photo <time class="datetime" datetime="2011-09-26T11:42:11">9-26-2011</time></p>
<p>Jane closed issue 12 <time class="datetime" datetime="2011-09-21T02:27:42">2011, September 21</time></p>
<p>Harry started using jQuery <abbr class="datetime" title="2011-08-12T14:51:03">Aug 12</abbr></p>
<p>Sent an email <time class="datetime" datetime="2001-12-25T11:21:53">2011 12/25</time></p>
<p>I was born <abbr class="datetime" title="1984-05-15T00:00:00">May 15th, 1984</abbr></p>

Turns into this by default

You opened this page opened time.

Someone posted something

John shared his photo

Jane closed issue 12

Harry started using jQuery Aug 12

Sent an email

I was born May 15th, 1984

However, you can change how they are displayed with different options.
Option 1 (Relativity rules) | Option 2 (Minimalist)

How to use

Download latest version here (last updated )

If you use tags other than time to markup the datetime. The tag should have ISO8601 datetime string as the value of title attribute.

HTML5 introduced a new tag called time that has datetime attribute. You can use the new time tag with ISO8601 datetime string as the value of datetime attribute.

Once you are ready, call the plugin like this

$(function() {

Optionally, you can pass an object to override the default setting.

When your define your masks, you can use any combination of flags from the list below to specify which information you want to show. Or none, if you don't want to :(


Here are the default setting values

var settings = {
shortDayNames: [
'Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'
longDayNames: [
'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday',
'Friday', 'Saturday'
shortMonthNames: [
'Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun',
'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'
longMonthNames: [
'January', 'February', 'March', 'April', 'May', 'June',
'July', 'August', 'September', 'October', 'November', 'December'
refreshRate: 60000,
pastMask: '%mmmm %d, %yyyy at %h:%MM%tt',
futureMask: '%mmmm %d, %yyyy at %h:%MM%tt',
masks: [
// within a minute
distance: 60,
mask: 'just now'
// within 2 minutes
distance: 120,
mask: 'about a minute ago'
// within 1 hour
distance: 3600,
mask: '%xm minutes ago'
// within 2 hours
distance: 7200,
mask: 'about an hour ago'
// within 24 hours
distance: 86400,
mask: '%xh hours ago'
// within 48 hours
distance: 172800,
mask: 'Yesterday at %h:%MM%tt'
// within this year
distance: 31556926,
mask: '%mmmm %d at %h:%MM%tt'

Got something?

If you have any question or feedback, drop me an email at

If there is a bug or problem, create a issue at GitHub or fork it and send a pull request.


MIT License