Getting Started With Datejs

November 27th, 2007 | Tutorial

Welcome grasshopper. Let us begin.

Step #1 - Pick your weapon

In order to move safely through the shadowy world of the JavaScript Date Class you must add the date.js file to your arsenal of tools.


<script type="text/javascript" src="date.js"></script>

You can download the latest release from or connect directly to the SVN source repository via

The date.js file can be found within the /build/ folder.

Datejs has traveled to many lands and returns with knowledge of over 150 individual Cultures. Supporting your language of choice is simple, just swap out the date.js file for another culture-specific file.


en-US [English (United States)]
<script type="text/javascript" src="date.js"></script>

en-US [English (United States)]
<script type="text/javascript" src="date-en-US.js"></script>

de-DE [German (Germany)]
<script type="text/javascript" src="date-de-DE.js"></script>

fr-FR [French (France)]
<script type="text/javascript" src="date-fr-FR.js"></script>

All 150+ CultureInfo files have been pre-compiled and are available within the same /build/ folder as date.js. Each culture file includes translations for many of the strings used in the Datejs library. Some strings have not been translated, although will be filled in over time as the community contributes.

Step #2 - Start your training

The Datejs library includes many helpful functions for easing the pain of developing with Dates and Times in JavaScript. Once the date.js file has been included into your page you can begin some serious training.

If you have not already done so, we highly recommend installing FireBug for FireFox. Among many things, Firebug allows you to execute custom JavaScript code directly in the browser without having to edit your source page — kind of like a command-line for JavaScript. Get it now. The Ninja waits.

Let's Get Started

Before diving deep into the library, let's first limber up with some stretching. Exploring the natural language syntax is a good place to start.

// Get today's date;

// Add 5 days to today;

// Get Friday of this week

// Get March of this year

// Is today Friday?;  // true|false

// What day is it?;

Everything ok? A little out of breath? Soooo sorry.

Now, some Date Assassin exercises.

// Get the first Monday of the year

// Get the last Friday of the year

// Set a date to the 15th of the current month at 4:30 PM,
// then add 90 days and make sure that date is a weekday,
// else move to the next weekday.
var d1 =
    .set({ day: 15, hour: 16, minute: 30 })
    .add({ days: 90 })
if (!d1.isWeekday()) {;

How about letting your users enter a few dates? Say into an <input> field or date picker? Included with the Datejs library is a powerful replacement for the native JavaScript Date parser.

The following examples all start with a String value that we convert into a Date object.

// Lets start simple. "Today"

// How about tomorrow?

// July 8?
Date.parse('July 8');

// With a year?
Date.parse('July 8th, 2007');

// And time?
Date.parse('July 8th, 2007, 10:30 PM');

// Get the date, move to Monday (if not already Monday),
// then alert the date to the user in a different format.
var d1 = Date.parse('8-Jul-2007');
if (! {
alert(d1.toString('dddd, MMMM d, yyyy'));

The library also includes some Number fun. In order to execute functions directly on JavaScript Number objects, the number must be wrapped in parentheses. This is a requirement of JavaScript. If the number is declared first, the parentheses are not required.

// Get a date 3 days from now

// 6 month ago

// 12 weeks from now
var n = 12;

// Get a date 30 days after a user supplied date
var d1 = Date.parse('07.15.2007');
var d2 = (30).days().after(d1);

Step #3 - Refine your skillz

You are nearing a state of Date Ninja-ness, but more experience is required.

Please be sure to check out the following list of resources for further training.

The Datejs Library also includes good size Test Suite, which is worth browsing to get a idea of what's possible.

Hope this helps.


  1. This is outstanding work; hope it takes off! One small thing: on the front page under Syntactic Sugar, I see this:

    // What date is next thrusday?

    Right, “thrusday” is a typo … but it’d sure be neat if the invisible Datejs ninja caught it….

    Comment by Kent Brewster — November 27, 2007 @ 3:01 pm

  2. Very cool stuff!

    Nice to see some real date handling in JavaScript.

    Any chance of supporting ISO 8601 dates?

    Import and export.


    Comment by Michael Kaply — November 28, 2007 @ 6:31 am

  3. What’s the chance that this will do standard unix time in the near future? What about checking the timezone of the client, and calculating other timezones (unix: PST: next tuesday + 5 years)?

    Comment by Issac Kelly — November 28, 2007 @ 6:57 am

  4. Great job on the library! – I believe we met at The Ajax Experience, I still have your card laying around. I’m sure we could collaborate with jQuery UI Datepicker. Once again, great job.

    Comment by Marc — November 28, 2007 @ 8:25 am

  5. Your code examples are using curly-quotes.

    Comment by Foob — November 28, 2007 @ 2:47 pm

  6. This is really amazing and powerful tool to manipulate date.

    Comment by Balasubramanian R — November 28, 2007 @ 9:15 pm

  7. Hi guys,

    Thank you for great lib. :)

    My only concert is SQL format for date is YYYY-MM-DD HH:MM:SS
    but your lib parses it like YYYY-DD-MM which is not correct.

    I tried canada english localization.

    Thank you again.

    Comment by Alex — November 29, 2007 @ 10:35 am

  8. Great tutorial. You guys rock

    Comment by jc — December 2, 2007 @ 10:17 pm

  9. needs a function to return a unix timestamp, unless I missed something — otherwise not very useful for professional developers. looks awesome though, great job

    Comment by Michael — December 18, 2007 @ 9:18 am

  10. That’s amazing! Very good work. I put a link on my site and share it to the german webdevelopers.


    Comment by Marc — December 20, 2007 @ 7:43 am

  11. […] Загрузить библиотеку | Как использовать […]

    Pingback by Datejs at RIA Revolution — January 23, 2008 @ 7:13 am

  12. Interesting, will have a look at this. The ordering of the dates is really not that big of a problem, since you could easily parse this erverside. Aslong as the year is with 4 digits it really comes down to splitting the sring, and reversing it.


    Split the string on “-” and look for the item in array with 4 digits. if not first then reverse array. Surely you should replace all / with -, . with – so your date can handle alot of different input from users.

    Comment by Kim Steinhaug — March 8, 2008 @ 8:25 am

  13. Michael

    try d.valueOf(); for milliseconds since midnight 01 January, 1970 UTC.

    its part of the javascript spec

    Comment by Killerkiwi — March 19, 2008 @ 8:00 pm

  14. Does this still work? Is it supported?

    The examples in the “Let’s get Started” do not seem to work —

    Date.friday is not a function

    is what the error console in Firefox has to say.


    Comment by Mayank Jain — April 6, 2008 @ 8:15 pm

  15. Or may be there are just more js files to include besides the date.js — the getting started page does not seem to mention it (or did I overlook it) — looking forward to a solution.



    Comment by Mayank Jain — April 6, 2008 @ 8:32 pm

  16. […] Zum Starten: […]

    Pingback by agimatec » Blog Archive » Javascript Framework: heute Datejs — April 15, 2008 @ 12:20 pm

  17. An idea…

    That is very cool (and useful), but it actually does the exact opposite of what I’m looking for. Its parsing abilities convert “Next Tuesday” to a date. I’m looking for is the ability to convert a date to a “human scale” output. All the date formatters let you pick any mix of month/day/year/time, but none of them create “natural” dates. For example, to humans “Yesterday” or “Tomorrow” is a lot more descriptive and easier to digest than “05/21/2008” or even “May 21, 2008”. Then in the next step (for a few days ago), maybe the time of the event matters, but for events that happened three weeks ago, it may not. What I envision is a date formatter that is passed the target date and an optional “comparison” date (which defaults to “now” if it’s omitted), plus an array (?) of format strings and “ranges” (i.e., for dates longer ago than 3 weeks, use this format string; for dates longer ago than 1 year, use this one, etc.); by default, it would use yesterday, today, and tomorrow for dates that fall into that range, with an optional time format string to append.

    This isn’t on the top of my to-do list right now, so I may write it when it gets there, unless you should end up doing it in the mean time 😉


    Comment by Eric — May 22, 2008 @ 8:16 am

  18. Hi,

    Very Cool Stuff!
    Its a good work done!

    I went through the Starters Kit.. and have a question.
    Say, if the user enters any random date, can that be converted to UTC Time Zone using the date.js lib

    Comment by Deepak — May 31, 2008 @ 10:50 pm

  19. Hi

    Really cool, thanks!

    There is an error when using “days ago” – it works perfectly for some days back (11 days ago) but above 11 it always calculates it as ‘yesterday, 12:00 AM’

    Comment by Chris — June 3, 2008 @ 1:18 pm

  20. Hey. I’m now to this and don’t exactly know where to get started . I’ve downloaded the scripts, but was specifically looking for a script to get a date 3 days from now to implement in an online agreement.

    Where does the script go, in the section or in the ?

    Please advise.

    Comment by Bob C — June 17, 2008 @ 1:12 am

  21. […] Get started with datejs […]

    Pingback by datejs - open-source JavaScript Date Library — June 17, 2008 @ 11:18 pm

  22. Absolutely amazing library. I was hoping someone had done something like this!

    Comment by Bob S — July 1, 2008 @ 8:21 pm

  23. Impressive. What I am looking for is a very simple extension:
    (3).workdays().fromNow() or (3).workdays().ago()

    optionally it could take a parameter list of days to skip, or a config with holidays.

    Comment by Michiel van der Blonk — July 10, 2008 @ 12:01 pm

  24. I am looking for a same extension as Michiel van der Blonk – I need to figure out future business days. Perl has a great module on cpan, datemanip, which I use for server side coding. Alas, for this requirement, I am working within the confines of a hosted CMS tool which gives little flexibility but to use JavaScript. Guess I can just check day name of returned value until it is a work day.

    Comment by Marianne M. — July 17, 2008 @ 1:39 pm

  25. […] ここから をクリックしてダウンロードするわけですが、 をダウンロードして、解凍すると build フォルダ内に date-ja-JP.js がありますので、plugins/wpng-calendar/js 内にコピーします。 そして、wpng-calendar.php ですが、Add the DateJS file で検索して wp_enqueue_script(’date-js’, get_bloginfo(’wpurl’) . ‘/wp-content/plugins/wpng-calendar/js/date-ja-JP.js’, null, ‘alpha-1′); と書き換えました。そして、それぞれアップロードです。 […]

    Pingback by #18 WordPress Google Calendar を利用して予定表を表示する | うずら — August 18, 2008 @ 7:02 am

  26. I used this for business day calculation. Anyone else try this or something similar?
    @sDate is start date field
    @eDate is end date field
    @loc is field to display business date result
    function popBusinessDays(sDate, eDate, loc){
    var sD = document.getElementById(sDate).value;
    var eD = document.getElementById(eDate).value;
    var bD = document.getElementById(loc);
    var bdsec = “”;
    var totdays = 0;
    var bdays = 0;
    if (sD != “” && eD != “” && bD != “”) {
    //get total days
    bdsec = Date.parse(eD) – Date.parse(sD);
    totdays = (bdsec/86400000); //convert millisec and make inclusive
    //get bus days
    for (var x=0; x <= totdays; x++) {
    if (Date.parse(sD).add(x).days().isWeekday()) {
    bdays += 1;
    bD.value = bdays;

    Comment by Jaime — October 8, 2008 @ 1:56 pm

  27. What error is this:

    [Exception… “‘TypeError: null’ when calling method: [nsIDOMEventListener::handleEvent]” nsresult: “0x8057001c (NS_ERROR_XPC_JS_THREW_JS_OBJECT)” location: “” data: no]

    Comment by vijay — October 22, 2008 @ 10:52 pm

  28. Can anyone give me some insight on acquiring the number of the week for the current date. Meaning 11/15/2008 is the 3rd week of November.

    Comment by Steve — November 15, 2008 @ 4:03 pm

  29. Please port to jquery this:


    Comment by Jah Jah Banker — December 9, 2008 @ 4:09 pm

  30. // What day is it?;

    …just a thought but looks like it should be a property of Date – i.e. “;”

    otherwise neat stuff!

    Comment by Jason — December 22, 2008 @ 8:33 pm

  31. […] Datejs (Opensource JavaScript Library) […]

    Pingback by Facelets, JavaScript, XHTML « Hobione’s Weblog — January 7, 2009 @ 6:26 pm

  32. Cool – sorted out my problem of parsing en-GB style dates in an instant.

    Comment by Ashley — January 27, 2009 @ 1:17 am

  33. Thanks for the guidance, sensei.

    Date Ninja asks: if I were sleeping and you were my alarm clock, how would you wake me up?

    TourVista answers: I wouldn’t… I’m no ding-a-ling!

    (See the Kentucky Fried Movie if you did not laugh.)

    Comment by TourVista — April 8, 2009 @ 4:00 pm

  34. Tried installing on Linux and it doesn’t work…I noticed some ^M at the end of lines which is a problem (usually happens when a windows file is improperly formatted for linux & Mac). When it becomes compatible for linux or Mac OS, I would be interested in trying it again : )

    Comment by Tiffany — April 27, 2009 @ 10:04 am

  35. Cool API’s. Ninja meets zen programming. Till now I used to hate programming in js, but just fell in love with JavaScript!!!

    Comment by bhatti — May 28, 2009 @ 5:49 am

  36. This is brilliant, you guys have saved me so much time!

    Comment by Ruth — July 24, 2009 @ 3:22 am

  37. method is not present. Help me!! should i need to include any other js?

    Comment by eliteBook — July 30, 2009 @ 9:35 am

  38. when i don’t type a year, i would like to force the default year to be in the FUTURE. for example, if i type 1/1, i would like that to be 1/1/2010, not 1/1/2009 in the past. any way to do this?

    Comment by barry — August 3, 2009 @ 12:48 pm

  39. …and i also can not get Date.isAfter to work… can’t find it in the date.js either… perhaps the doc is beyond the actual code? or is there another .js to include?

    Comment by barry — August 3, 2009 @ 9:16 pm

  40. […] Getting Started with Datejs… […]

    Pingback by script » Blog Archive » Datejs is an open-source JavaScript Date Library. — August 29, 2009 @ 7:09 am

  41. When i Date.parse(‘Sun Aug 30 12:00:00 GMT 2009’), i get ‘Sun Aug 23 08:00:00 EDT 2009’…. everything is right except for the date, it should be 30th not the 23rd. I tried it on my local and on a salesforce server and i get the same result, except for when i try it on this website. Here is the very simple code i tried below.
    $(document).ready(function() {
    var text= ‘Sun Aug 30 12:00:00 GMT 2009’;

    Comment by kunle — August 29, 2009 @ 3:30 pm

  42. Trying to use isBefore and does not appear to be a method. Using downloaded zip and (date-en-GB.js) as opposed to svn. Was this a recently added method or have I messed up?

    Comment by Phoebe Bright — October 8, 2009 @ 7:36 am

  43. How can I change the default format of the dates from mm/dd/yyyy to dd/mm/yyyy or yyyy/mm/dd ?

    If I type “5/11” I want the ninja to understand that I mean Nov 5th, not May 11th.
    The CultureInfo files don’t seem to have an option for this :(

    Comment by kjkjh — November 3, 2009 @ 1:48 am

  44. while trying to use toString() i get into infinite loop which ends with too many recursion error. Do i something wrong or this could be bug? i don’t want to enter specific format, would like to have default behavior.

    Comment by user — November 24, 2009 @ 5:45 am

  45. You should probably update that download link up there with a newer version from SVN, it’s more than a year old now and many of the documented features (compare, isAfter, etc) are missing altogether.

    Comment by Arkadiy — December 2, 2009 @ 1:48 pm

  46. Great work – thanks!

    I too would like to see some way of supporting ISO 8601 dates – for me, I need a way to display Ordinal Dates.
    Although I need only two digits for the year. (i.e. 10_025 insead of 2010_025)

    ISO 8601 dates were mentioned in another comment above with the following links:

    Hope there is a way for this, it would save me a headache!

    Import and export.

    Comment by Dakkar — January 25, 2010 @ 1:46 pm

  47. As someone mentioned earlier:
    “45.You should probably update that download link up there with a newer version from SVN, it’s more than a year old now and many of the documented features (compare, isAfter, etc) are missing altogether.”

    This looks like a great library and I hate complaining about awesome free software, but your website lists code examples that are up to date with the post alpha release, but there seems to be nowhere to download it.

    I think maybe it is available here:

    …but, I’m not sure. I’m trying to use the isAfter() function. I wouldn’t mind jumping through a few hoops to get to it, but a hint as to which hoops to jump through would be helpful.

    Comment by Trevor — February 17, 2010 @ 6:41 pm

  48. Seriously….you actually deleted my comment?

    Comment by Trevor — February 18, 2010 @ 1:48 pm

  49. oops, guess not…sorry!! :(

    Comment by Trevor — February 18, 2010 @ 1:48 pm

  50. it’s very outstanding! but why not ‘Date.friday();’ work?

    Comment by windstamp — February 20, 2010 @ 12:57 am

  51. Some functions are not working properly

    // Get a date 30 days after a user supplied date
    var d1 = Date.parse(‘07.15.2007’);
    var d2 = (30).days().after(d1);

    the function after give js error
    Please check and let me inform

    Amit srivastava

    Comment by Amit Srivastava — March 17, 2010 @ 10:27 pm

  52. Seems to have trouble converting “12:00 PM”:
    2010-06-23 12:00 AM – parses correctly
    2010-06-23 12:00 PM – parses as 12 AM
    2010-06-23 01:00 AM – parses correctly
    2010-06-23 01:00 PM – parses correctly

    Comment by Heath — June 23, 2010 @ 8:47 am

  53. Disregard that, I’m silly.

    Comment by Heath — June 23, 2010 @ 8:54 am

  54. Quick and clean jQuery DatePicker integration:

    Modify DatePicker’s parseDate function. After initial validation:

    if (value == ”) return null;

    Comment out the rest of the function. Replace with:

    var dateJsParseAttemptDate = Date.parse(value);
    if(dateJsParseAttemptDate) return dateJsParseAttemptDate;
    throw ‘Invalid date’;

    Comment by Igor — July 6, 2010 @ 3:55 pm

  55. Damm. If only I’d come across this two weeks ago. I s’pose I can play with dates in JS the same way I do in Rails now :)


    Comment by Danny Smith — July 20, 2010 @ 2:24 pm

  56. Will someone please tell me why we can’t get Date.parse to correctly parse 12:00 AM or 12:00 PM????

    It is not recognizing 12:00 PM as a valid value. And 12:00 AM is parsed as 12:00 PM.

    We’ve stripped out everything but jquery 1.4.3 and datejs.

    It’s pretty damn basic, so I’m not sure what else we should try.


    Comment by patrick — November 18, 2010 @ 7:44 am

  57. nevermind… you really need to update the links to the current code version :-)

    Comment by patrick — November 18, 2010 @ 8:01 am

  58. I changed the the getDayName function to accept 1,2 or 3 as the abbreviating parameter as I couldn’t find anyway to getDayInitial.

    return abbrev==3?

    Comment by Scilly_guy — December 27, 2010 @ 7:25 am

  59. […] This is absolutely a library I recommend using if you need to work with date and time in JavaScript. Be sure to check out their getting started guide. […]

    Pingback by Date and time handling in JavaScript using DateJs | Alexander Nyquist — March 19, 2011 @ 6:10 am

  60. How to print timezone?

    hh:mm:ss ??

    Comment by Aakaash — May 13, 2011 @ 12:04 am

  61. […] 2 imports the Datejs library. You will have to download it and install via these instructions. Lines 5-23 calculates each of the date elements that I will need to piece together the final […]

    Pingback by JavaScript Date Ranges/Calculations with Datejs — July 30, 2011 @ 1:18 am

  62. Hi,
    Great script. Only I think I found a potentially potent bug!
    I am using the mi-NZ version and using Date.parse(“dd/mm/yyyy hh:mm tt”) format i.e. 30/09/2011 11:07 pm however 12:07 am gives me a date with getHours() = 12 and 12:07pm gives me a date with getHours() = 12. Everything else is working fine ie. 1am returns 1, 2am returns 2, 2pm returns 14 etc. 12am should return 0?

    How would I go about correcting this?


    Comment by Le-roy — September 29, 2011 @ 4:59 pm

  63. very good library, saved me much time! THX!

    Comment by ringo — October 10, 2011 @ 6:22 am

  64. Good script but don’t seems to work with Jquery UI Date picker… :/

    Comment by Romain — November 28, 2011 @ 6:34 am

  65. I think this page is deprecated you should use the google-code page instead (

    don’t forget to include “sugarpak.js” to use all the syntactical sugar used in the examples like “after()”.

    Comment by binary — January 31, 2012 @ 7:31 am

  66. Note has not been updated since 2007.


    Comment by Martin Cleaver — February 16, 2012 @ 3:29 am

  67. I am having a conflict when using DateJS on the same page as ExtJS. Does DateJS support its own namespace so it can be referenced without naming conflicts with other libraries?

    Comment by Steve — March 4, 2012 @ 6:02 pm

  68. Hello,
    This is excellent work and saved a tones of time for me,
    Thank you !

    Comment by Harpreet — March 30, 2012 @ 7:21 am

  69. Fantastic work! I love your method names and how well you made it english-like.

    Comment by Anthony — April 4, 2012 @ 12:17 pm

  70. Would be good, if someone can add a method which returns end of day as well!

    Comment by Discover — April 18, 2012 @ 3:46 am

  71. Hi guys… JsSimpleDateFormat can parse the formatted string back to the Date Object

    Two ways functions.. Could the others do this?
    It uses format as Java format

    Comment by John — May 14, 2012 @ 11:10 pm

  72. […] you looked at datejs? (using the appropriate globalization pack to parse dd/mm/yyyy […]

    Pingback by How to check if input date is equal to today's date? | Easy jQuery | Free Popular Tips Tricks Plugins API Javascript and Themes — May 21, 2012 @ 3:23 am

  73. Thank you so much, works great for me.
    I’ve used it to parse dates into UNIX datetime format from a standard form.


    Comment by Dehsinotsa — May 25, 2012 @ 3:57 am

  74. […] Datejs you should parse the values from the input field using Date.parse(startDate). Check out the Getting Started. If you decide not to use DateJs, you could append getTime() to the startTime var. (e.g. – […]

    Pingback by Comparing Time using Javascript | Easy jQuery | Free Popular Tips Tricks Plugins API Javascript and Themes — June 2, 2012 @ 12:02 am

Leave a comment