JavaScript Date Format

Update: The documentation below has been updated for the new Date Format 1.2. Get it now!

Although JavaScript provides a bunch of methods for getting and setting parts of a date object, it lacks a simple way to format dates and times according to a user-specified mask. There are a few scripts out there which provide this functionality, but I've never seen one that worked well for me… Most are needlessly bulky or slow, tie in unrelated functionality, use complicated mask syntaxes that more or less require you to read the documentation every time you want to use them, or don't account for special cases like escaping mask characters within the generated string.

When choosing which special mask characters to use for my JavaScript date formatter, I looked at PHP's date function and ColdFusion's discrete dateFormat and timeFormat functions. PHP uses a crazy mix of letters (to me at least, since I'm not a PHP programmer) to represent various date entities, and while I'll probably never memorize the full list, it does offer the advantages that you can apply both date and time formatting with one function, and that none of the special characters overlap (unlike ColdFusion where m and mm mean different things depending on whether you're dealing with dates or times). On the other hand, ColdFusion uses very easy to remember special characters for masks.

With my date formatter, I've tried to take the best features from both, and add some sugar of my own. It did end up a lot like the ColdFusion implementation though, since I've primarily used CF's mask syntax.

Before getting into further details, here are some examples of how this script can be used:

var now = new Date();

now.format("m/dd/yy");
// Returns, e.g., 6/09/07

// Can also be used as a standalone function
dateFormat(now, "dddd, mmmm dS, yyyy, h:MM:ss TT");
// Saturday, June 9th, 2007, 5:46:21 PM

// You can use one of several named masks
now.format("isoDateTime");
// 2007-06-09T17:46:21

// ...Or add your own
dateFormat.masks.hammerTime = 'HH:MM! "Can\'t touch this!"';
now.format("hammerTime");
// 17:46! Can't touch this!

// When using the standalone dateFormat function,
// you can also provide the date as a string
dateFormat("Jun 9 2007", "fullDate");
// Saturday, June 9, 2007

// Note that if you don't include the mask argument,
// dateFormat.masks.default is used
now.format();
// Sat Jun 09 2007 17:46:21

// And if you don't include the date argument,
// the current date and time is used
dateFormat();
// Sat Jun 09 2007 17:46:22

// You can also skip the date argument (as long as your mask doesn't
// contain any numbers), in which case the current date/time is used
dateFormat("longTime");
// 5:46:22 PM EST

// And finally, you can convert local time to UTC time. Either pass in
// true as an additional argument (no argument skipping allowed in this case):
dateFormat(now, "longTime", true);
now.format("longTime", true);
// Both lines return, e.g., 10:46:21 PM UTC

// ...Or add the prefix "UTC:" to your mask.
now.format("UTC:h:MM:ss TT Z");
// 10:46:21 PM UTC

Following are the special characters supported. Any differences in meaning from ColdFusion's dateFormat and timeFormat functions are noted.

Mask	Description
`d`	Day of the month as digits; no leading zero for single-digit days.
`dd`	Day of the month as digits; leading zero for single-digit days.
`ddd`	Day of the week as a three-letter abbreviation.
`dddd`	Day of the week as its full name.
`m`	Month as digits; no leading zero for single-digit months.
`mm`	Month as digits; leading zero for single-digit months.
`mmm`	Month as a three-letter abbreviation.
`mmmm`	Month as its full name.
`yy`	Year as last two digits; leading zero for years less than 10.
`yyyy`	Year represented by four digits.
`h`	Hours; no leading zero for single-digit hours (12-hour clock).
`hh`	Hours; leading zero for single-digit hours (12-hour clock).
`H`	Hours; no leading zero for single-digit hours (24-hour clock).
`HH`	Hours; leading zero for single-digit hours (24-hour clock).
`M`	Minutes; no leading zero for single-digit minutes. Uppercase M unlike CF `timeFormat`'s m to avoid conflict with months.
`MM`	Minutes; leading zero for single-digit minutes. Uppercase MM unlike CF `timeFormat`'s mm to avoid conflict with months.
`s`	Seconds; no leading zero for single-digit seconds.
`ss`	Seconds; leading zero for single-digit seconds.
`l` or `L`	Milliseconds. `l` gives 3 digits. `L` gives 2 digits.
`t`	Lowercase, single-character time marker string: a or p. No equivalent in CF.
`tt`	Lowercase, two-character time marker string: am or pm. No equivalent in CF.
`T`	Uppercase, single-character time marker string: A or P. Uppercase T unlike CF's t to allow for user-specified casing.
`TT`	Uppercase, two-character time marker string: AM or PM. Uppercase TT unlike CF's tt to allow for user-specified casing.
`Z`	US timezone abbreviation, e.g. EST or MDT. With non-US timezones or in the Opera browser, the GMT/UTC offset is returned, e.g. GMT-0500 No equivalent in CF.
`o`	GMT/UTC timezone offset, e.g. -0500 or +0230. No equivalent in CF.
`S`	The date's ordinal suffix (st, nd, rd, or th). Works well with `d`. No equivalent in CF.
`'…'` or `"…"`	Literal character sequence. Surrounding quotes are removed. No equivalent in CF.
`UTC:`	Must be the first four characters of the mask. Converts the date from local time to UTC/GMT/Zulu time before applying the mask. The "UTC:" prefix is removed. No equivalent in CF.

And here are the named masks provided by default (you can easily change these or add your own):

Name	Mask	Example
default	ddd mmm dd yyyy HH:MM:ss	Sat Jun 09 2007 17:46:21
shortDate	m/d/yy	6/9/07
mediumDate	mmm d, yyyy	Jun 9, 2007
longDate	mmmm d, yyyy	June 9, 2007
fullDate	dddd, mmmm d, yyyy	Saturday, June 9, 2007
shortTime	h:MM TT	5:46 PM
mediumTime	h:MM:ss TT	5:46:21 PM
longTime	h:MM:ss TT Z	5:46:21 PM EST
isoDate	yyyy-mm-dd	2007-06-09
isoTime	HH:MM:ss	17:46:21
isoDateTime	yyyy-mm-dd'T'HH:MM:ss	2007-06-09T17:46:21
isoUtcDateTime	UTC:yyyy-mm-dd'T'HH:MM:ss'Z'	2007-06-09T22:46:21Z

A couple issues:

In the unlikely event that there is ambiguity in the meaning of your mask (e.g., m followed by mm, with no separating characters), put a pair of empty quotes between your metasequences. The quotes will be removed automatically.
If you need to include literal quotes in your mask, the following rules apply:
- Unpaired quotes do not need special handling.
- To include literal quotes inside masks which contain any other quote marks of the same type, you need to enclose them with the alternative quote type (i.e., double quotes for single quotes, and vice versa). E.g., date.format('h "o\'clock, y\'all!"') returns "6 o'clock, y'all". This can get a little hairy, perhaps, but I doubt people will really run into it that often. The previous example can also be written as date.format("h") + "o'clock, y'all!".

Here's the code:

/*
 * Date Format 1.2.3
 * (c) 2007-2009 Steven Levithan <stevenlevithan.com>
 * MIT license
 *
 * Includes enhancements by Scott Trenda <scott.trenda.net>
 * and Kris Kowal <cixar.com/~kris.kowal/>
 *
 * Accepts a date, a mask, or a date and a mask.
 * Returns a formatted version of the given date.
 * The date defaults to the current date/time.
 * The mask defaults to dateFormat.masks.default.
 */

var dateFormat = function () {
	var	token = /d{1,4}|m{1,4}|yy(?:yy)?|([HhMsTt])\1?|[LloSZ]|"[^"]*"|'[^']*'/g,
		timezone = /\b(?:[PMCEA][SDP]T|(?:Pacific|Mountain|Central|Eastern|Atlantic) (?:Standard|Daylight|Prevailing) Time|(?:GMT|UTC)(?:[-+]\d{4})?)\b/g,
		timezoneClip = /[^-+\dA-Z]/g,
		pad = function (val, len) {
			val = String(val);
			len = len || 2;
			while (val.length < len) val = "0" + val;
			return val;
		};

	// Regexes and supporting functions are cached through closure
	return function (date, mask, utc) {
		var dF = dateFormat;

		// You can't provide utc if you skip other args (use the "UTC:" mask prefix)
		if (arguments.length == 1 && Object.prototype.toString.call(date) == "[object String]" && !/\d/.test(date)) {
			mask = date;
			date = undefined;
		}

		// Passing date through Date applies Date.parse, if necessary
		date = date ? new Date(date) : new Date;
		if (isNaN(date)) throw SyntaxError("invalid date");

		mask = String(dF.masks[mask] || mask || dF.masks["default"]);

		// Allow setting the utc argument via the mask
		if (mask.slice(0, 4) == "UTC:") {
			mask = mask.slice(4);
			utc = true;
		}

		var	_ = utc ? "getUTC" : "get",
			d = date[_ + "Date"](),
			D = date[_ + "Day"](),
			m = date[_ + "Month"](),
			y = date[_ + "FullYear"](),
			H = date[_ + "Hours"](),
			M = date[_ + "Minutes"](),
			s = date[_ + "Seconds"](),
			L = date[_ + "Milliseconds"](),
			o = utc ? 0 : date.getTimezoneOffset(),
			flags = {
				d:    d,
				dd:   pad(d),
				ddd:  dF.i18n.dayNames[D],
				dddd: dF.i18n.dayNames[D + 7],
				m:    m + 1,
				mm:   pad(m + 1),
				mmm:  dF.i18n.monthNames[m],
				mmmm: dF.i18n.monthNames[m + 12],
				yy:   String(y).slice(2),
				yyyy: y,
				h:    H % 12 || 12,
				hh:   pad(H % 12 || 12),
				H:    H,
				HH:   pad(H),
				M:    M,
				MM:   pad(M),
				s:    s,
				ss:   pad(s),
				l:    pad(L, 3),
				L:    pad(L > 99 ? Math.round(L / 10) : L),
				t:    H < 12 ? "a"  : "p",
				tt:   H < 12 ? "am" : "pm",
				T:    H < 12 ? "A"  : "P",
				TT:   H < 12 ? "AM" : "PM",
				Z:    utc ? "UTC" : (String(date).match(timezone) || [""]).pop().replace(timezoneClip, ""),
				o:    (o > 0 ? "-" : "+") + pad(Math.floor(Math.abs(o) / 60) * 100 + Math.abs(o) % 60, 4),
				S:    ["th", "st", "nd", "rd"][d % 10 > 3 ? 0 : (d % 100 - d % 10 != 10) * d % 10]
			};

		return mask.replace(token, function ($0) {
			return $0 in flags ? flags[$0] : $0.slice(1, $0.length - 1);
		});
	};
}();

// Some common format strings
dateFormat.masks = {
	"default":      "ddd mmm dd yyyy HH:MM:ss",
	shortDate:      "m/d/yy",
	mediumDate:     "mmm d, yyyy",
	longDate:       "mmmm d, yyyy",
	fullDate:       "dddd, mmmm d, yyyy",
	shortTime:      "h:MM TT",
	mediumTime:     "h:MM:ss TT",
	longTime:       "h:MM:ss TT Z",
	isoDate:        "yyyy-mm-dd",
	isoTime:        "HH:MM:ss",
	isoDateTime:    "yyyy-mm-dd'T'HH:MM:ss",
	isoUtcDateTime: "UTC:yyyy-mm-dd'T'HH:MM:ss'Z'"
};

// Internationalization strings
dateFormat.i18n = {
	dayNames: [
		"Sun", "Mon", "Tue", "Wed", "Thu", "Fri", "Sat",
		"Sunday", "Monday", "Tuesday", "Wednesday", "Thursday", "Friday", "Saturday"
	],
	monthNames: [
		"Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec",
		"January", "February", "March", "April", "May", "June", "July", "August", "September", "October", "November", "December"
	]
};

// For convenience...
Date.prototype.format = function (mask, utc) {
	return dateFormat(this, mask, utc);
};

Download it here (1.2 KB when minified and gzipped).

Note that the day and month names can be changed (for internationalization or other purposes) by updating the dateFormat.i18n object.

If you have any suggestions or find any issues, lemme know.

Want to learn about aphantasisa and hyperphantasia, the Shen Yun cult, or unmasking cult leader Karen Zerby? Check out my new blog at Life After Tech.

377 thoughts on “JavaScript Date Format”

Pingback: Javascript Date extension
Anton says:

April 16, 2010 at 6:42 am

oh, thanks. realy usefull thing.
Ananya says:

April 29, 2010 at 7:30 am

I have three dates like date 1,date 2,date 3(Format-dd/mm/yyyy).
In that all dates can be entered between nov to feb month.
date 1 and date 2 should have 1 week gap between them no matter of date1 should be greater than date 2.but 1 week can should be dere.
If i enter 1 row for 2010 year again i should not enter for 2010.

Can anyone say the validation for this.I am workin in VB.NET

Thanks in Advance.
Labsy says:

May 3, 2010 at 5:25 pm

Hi,

seems great and extensible code, but since I am just a copy-paste programmer, please, could someone help me implement this function with simple HTML form.
I’d like to check & alter user’s input into textfield, so to format it corectly for insertion in database, like this:

(ok, this sample DOES NOT work)
But question is if this function can be used to correct user input like in my case?
thanx!
singularity says:

May 12, 2010 at 9:24 am

If I need a date is format say May 12, 2010. Do I have to do something lke this:

exercise 1

var dt = new Date();
//var month = currentTime.getMonth()+1;
//var day = currentTime.getDate();
//var year = currentTime.getFullYear();
dateFormat(dt, “mmm, dS, yyyy”);
document.write(month +”/” +day +”/” +year);

Thanks for the help
Pingback: Tims Blog » Blog Archive » Problems resolved
Davide says:

June 16, 2010 at 11:38 am

Hi,
it’s a pleasure to use your library, simple, fast and well done!

I introduced a little variant, to handle iso-8601, handled by JAXB, the library I’m using to read and write JSON objects.

When you use the ‘o’ switch, you rightly writes the time zone like ‘+0200’, however iso-8601 uses ‘:’ character, to separate hours to minutes, like ‘+02:02’

this is what I change:
o:(o > 0 ? “-” : “+”) + (pad(Math.floor(Math.abs(o) / 60),2)+”:”+pad(Math.abs(o) % 60,2)),

Thank’s a lot again!
Ciao, Davide.
rblon says:

June 30, 2010 at 11:23 am

Thanks for this nice script.
It would be perfect if it has a function to parse a date for a given mask.
Pingback: Good Javascript Date Format Resource « Roy Jin
satya rathore says:

July 9, 2010 at 6:44 am

very helpful to find the javascript date time…
aka Pipo says:

July 22, 2010 at 2:32 am

Good work. Thanks!!!
Jason Palmer says:

August 3, 2010 at 11:25 am

Hello, I wanted to report a bug fix to this library.

I noticed that if a text field had a value already it was showing the wrong year.

The reason for this is that the function “getYear()” was used in two places.

Changing this to “getFullYear()” fixed the issue.
trevor says:

August 9, 2010 at 1:07 pm

Hi,

It seems there is a problem in IE7 — maybe I’m doing something wrong, but the script causes a complete javascript failure:

“Exception thrown and not caught”
About 23 lines down from “var dateFormat = function(){“….

you have:
“if (isNaN(date)) throw SyntaxError(“invalid date”);”

Should the function itself be wrapped in a try/catch?

-trevor
trevor says:

August 9, 2010 at 1:13 pm

Hmmm, it seems IE7 trips over this:

var date = new Date(Fri Jul 23 23:21:11 +0000 2010);

var dateString = date.format(“h:MM TT mmm dS”);

dateString becomes : 12:NaN PM NaN

Thoughts?
Krishna says:

August 20, 2010 at 2:14 am

Thank you. Cool stuff!!!
Tom says:

August 27, 2010 at 4:22 pm

It’s wonderfull!!!! thanks a lot….
wajhi says:

September 2, 2010 at 12:24 pm

Very nice piece of code thanks
ZQ says:

September 7, 2010 at 10:50 am

This is superb. Thanks a million.
Pingback: Javascript Date formatting « Random thoughts about things
dan says:

September 19, 2010 at 6:07 am

Thanx man!
Pingback: Cliente web de Twitter basado en @Anywhere, usando sólo HTML y Javascript // LDAblog
reycute says:

October 7, 2010 at 5:54 am

Thanks! You’ve made my day.
Chris says:

October 22, 2010 at 11:17 am

@trevor I had the same problem.

I was getting a date back from our servers as yyyy-mm-dd. When I passed that string to dateFormat() it threw an exception in IE only, not in any other browser.

To correct that I changed my call to this:
dateFormat(strDate.replace(/-/g, ‘/’), “mm-dd-yyyy” );

Problem solved.
Pingback: Node.js – Date formatting — carlfurrow.com
Tim says:

November 18, 2010 at 12:24 pm

@Chris

I was having the same problems as @trevor and some others, mostly due to the fact that this script relies on the default Date parsing, which IE must handle a bit differently than other browsers.

I was trying to take the date that was returned from a Blogger JSON feed, but was unable to get the formatting to work in IE. I used your code:

dateFormat(strDate.replace(/-/g, ‘/’), “fullDate”);

But I also had to add a .substr(0,9) to isolate YYYY/MM/DD from the rest of the Blogger date formatting. As mentioned, this script is meant for dealing with Date objects not strings, so my method is a bit of a messy hack, but it works for what I need it for.

Once I got the string formatted properly, Steve’s formatting script was perfect. Thanks for that Steve!
David Chambers says:

November 21, 2010 at 6:56 am

I’ve created a jQuery plugin (inspired by this code) for localizing dates and times. It retrieves date, time, and time zone information from the HTML5 `time` element’s `datetime` attribute, and updates both the displayed text and the value of the `datetime` attribute in accordance with the specified format string.

At its simplest, localizing date and times using the plugin takes just a few characters.

$(‘time’).localize();

The plugin is highly flexible and supports non-English languages. The project lives on Bitbucket: http://bitbucket.org/davidchambers/jquery.localize.
Gareth says:

November 22, 2010 at 11:35 am

Awesome – exactly what I was after. Saved me ages writing my own, cheers!

G
meathive says:

November 24, 2010 at 2:34 am

Thanks, man, awesome library. You may have more formatting options than PHP’s date()!
Mike M says:

November 24, 2010 at 10:30 am

I am running into an issue where having the client computer in a timezone that’s UTC/GMT offset includes minutes such as Kathmandu (GMT +5:45) causes an unexpected result. Here’s the usage:

var msTime = 1290579300033;
var date = new Date(msTime);

var dateFormatString = “mm/dd/yyyy HH:MM:ss”;
var result = date.format(dateFormatString);

// Actual result = 11/24/2010 06:15:00 GMT
// Expected result = 11/24/2010 06:00:00 GMT
Audrius S. says:

November 25, 2010 at 9:56 am

Great library, have been using it for a while and found it very useful. Thanks for sharing!
Mike M says:

November 25, 2010 at 11:12 am

I withdraw my comment. It turns out the issue was occurring elsewhere.
Jack says:

November 27, 2010 at 11:25 am

If you are accustomed with Java, try it

http://webdeveloper.earthweb.com/repository/javascripts/2009/03/880961/JsSimpleDateFormat-demo.html

It uses the same syntax as used by Java SimpleDateFormat
Jaxon says:

November 28, 2010 at 12:49 am

I found this date plugin for jQuery…

http://plugins.jquery.com/project/fIsForFormat

It’s got some pretty cool stuff I haven’t seen elsewhere.
shailesh says:

December 16, 2010 at 5:24 am

Hi,
As I want to use this kind of date picker (http://www.projectcodegen.com/JQueryDateTimePicker.aspx),I know Its mixup of jquery + java script but when i tried to give its format than it is showing me random result in textbox so please help me.I am using it with below syntax
$(‘#mydatepicker’).datetimepicker({‘DateFormat: ‘dd/mm/yyyy hh:MM tt’});

With Other all the formats it is working fine like mm/dd/yyyy ….etc. but when i give dd/mm/yyyy hh:MM tt format than only its performing random result so plz give me reply as soon as possible….Thanks In Advance.
Pingback: How to get current time and date in python | TechByt
Chris says:

January 17, 2011 at 7:30 pm

I am using this with Firefox 3.x and Chrome without issue, but when I try to run it in Safari or Mobile Safari (iPad) I get the following:

JavaScript Error on Line 38
http://…/javascripts/date.format.js
SyntaxError: invalid date

The format I am passing in is like this: “2011-01-15T14:55:14-08:00”.

I tried using the trick of subbing ‘-‘ for ‘/’, but that didn’t seem to help…

Any suggestions on how to fix?
Pingback: Handling time and date in R « DECISION STATS
Pingback: Parse Twitter & Facebook feeds with jQuery » jesal gadhia
Pingback: jQuery.durationpicker plugin
David Votrubec says:

January 24, 2011 at 6:21 pm

I used your dateformat in jquery durationpicker plugin.
http://demos.davidjs.com/durationpicker.zip
Clarence Fredericks says:

February 7, 2011 at 11:24 am

I came across a brand new JavaScript library called jPaq which provides a function that closely emulates PHP’s date function. Documentation for this function can be found here: http://jpaq.org/documentation/Date.prototype.format%28%29/1.0/.
Data Do IT says:

February 8, 2011 at 12:06 pm

Works perfectly! Used in the CodeCharge Studio framework.
Data Do IT says:

February 8, 2011 at 11:36 pm

I should add that I too had to use the

dateFormat(strDate.replace(/-/g, ‘/’), “mm-dd-yyyy” );

workaround for IE8 and FF3.
Jesse says:

February 11, 2011 at 1:13 am

Very helpful and easy to use. Much obliged to ya!
Pingback: Mix the following ingredients jQuery AJAX, jQuery templating, SharePoint REST api and apostrophes? « All things dev
Alexander says:

March 7, 2011 at 5:44 am

It’s all good, but would be nice to have method for parsing all these formats back into Date object.
Because, for instance, i have filter on web page, that stores filter control values in text form (for sending via URL, etc). I need some specific format for using in DB2 SQL function, but this format is not recognized by standard Date.parse method! So, now I need to invent something…
Jonas says:

March 9, 2011 at 4:24 am

This is awesome! This should be included in the official Javascript language IMO. Very helpful. Thanks!

Jonas
NewBoy says:

March 11, 2011 at 7:28 am

Thank you very much!
Zack says:

March 16, 2011 at 3:34 pm

Great article. I wanted to point out that your example and reference table are backwards for minutes and months.

m and mm are minutes

M and MM are months
Pingback: Date Selector in Titanium – Creating an iCal Look-Alike | DevDojo

377 thoughts on “JavaScript Date Format”

Leave a Reply