Skip to content


Subversion checkout URL

You can clone with
Download ZIP
A fully customisable 'time ago in words' implementation for use in the browser
branch: master

Merge pull request #1 from obazoud/01_readme_fix

Fix humanized_time_span sample
latest commit c30b059d15
@GrouchPotato authored
Failed to load latest commit information.
humanized_time_span.js added a license


humanized_time_span returns the difference between two Dates as a nice, human string for use in the browser.


Include the script (it's native JS so doesn't require anything else) and you're ready to go.


humanized_time_span(date, ref_date, date_formats, time_units)

Only date is required.


humanized_time_span("2010/09/10 10:00:00") => "3 days ago" (using now as a reference)

humanized_time_span("2010/09/10 10:00:00", "2010/09/10 12:00:00") => "2 hours ago"


Custom date formats can be set as follows:

var custom_date_formats = {
  past: [
    { ceiling: 60, text: "less than a minute ago" },
    { ceiling: 86400, text: "$hours hours, $minutes minutes and $seconds seconds ago" },
    { ceiling: null, text: "$years years ago" }
  future: [
    { ceiling: 60, text: "in less than a minute" },
    { ceiling: 86400, text: "in $hours hours, $minutes minutes and $seconds seconds time" },
    { ceiling: null, text: "in $years years" }

humanized_time_span("2010/09/10 10:00:00", "2010/09/10 10:00:05", custom_date_formats) 
  => "less than a minute ago"
humanized_time_span("2010/09/10 10:00:00", "2010/09/10 17:01:25", custom_date_formats) 
  => "5 hours, 1 minute and 25 seconds ago"
humanized_time_span("2010/09/10 10:00:00", "2012/09/10 10:00:00", custom_date_formats) 
  => "in 2 years"

Here the date format's ceiling is in seconds. Formats are walked through until one is reached where the ceiling is more than the difference between the two times or is null.

Please note that the last date format provided must not have a ceiling.

Variables in the format text should be prefixed with a $. eg. $xxx where xxx is the name of the time unit. The text should always be written in the plural (eg. "$years years ago") and the text will be automatically de-pluralized if, say in this case, there is only 1 year.

For those who live by different time rules, time_units can also be customised:

var custom_date_formats = [
  { ceiling: null, text: "$moggles moggles, $tocks tocks and $ticks ticks ago" },

var custom_time_units = [
  [20, 'moggles'],
  [10, 'tocks'],
  [1, 'ticks']
time_ago("2010/01/01 00:00:00", "2010/01/01 00:00:53", custom_date_formats, custom_time_units) 
  => "2 moggles, 1 tock and 3 ticks ago"

Custom date formats will have to be used when using custom time_units.

the default time units are:

[31556926, 'years'],
[2629744, 'months'],
[86400, 'days'],
[3600, 'hours'],
[60, 'minutes'],
[1, 'seconds']
Something went wrong with that request. Please try again.