type: widget
release: 0.0
priority: (undecided)
status: in planning
documentation: N/A
demo: http://jquery-ui.googlecode.com/svn/branches/labs/mask/demos/mask/default.html
1 - Description:
The mask plugin is a port of the maskedinput plugin by Josh Bush (http://digitalbush.com/projects/masked-input-plugin/) which has been extended upon.
[From digitalbush.com]
It allows a user to more easily enter fixed width input where you would like them to enter the data in a certain format (dates,phone numbers, etc). A mask is defined by a format made up of mask literals and mask definitions. Any character not in the definitions list below is considered a mask literal. Mask literals will be automatically entered for the user as they type and will not be able to be removed by the user. The following mask definitions are predefined:
- a (lowercase a) - Represents an alpha character (A-Z,a-z)
- # (pound) - Represents a numeric character (0-9)
- * (asterisk) - Represents an alphanumeric character (A-Z,a-z,0-9)
- ? (question mark) - Defines a starting point for partial mask input.
2 - Visual Design:

3 - Functional Specifications/Requirements:
(Detailed description of how the script will be structured: defaults, options, architecture, extensibility, etc.)
Getters:
Defaults:
- mask: ''
- placeholder: '_'
- completed: null
- allowPartials: false
Definitions: Predefined character definitions from which regular expressions are generated
definitions: {
'#': "[\\d]",
'a': "[A-Za-z]",
'*': "[A-Za-z0-9]"
}
Usage:
Applying a basic mask to an input/element:
$("#date").mask({ mask: "##/##/####"});
Optionally, if you are not satisfied with the underscore ('_') character as a placeholder, you may pass an optional argument to the maskedinput method.
$("#date").mask({ mask: "##/##/####", placeholder:" " });
Opitionally, if you would like to allow the user to enter a partial value, and retain that value when the input has lost focus.
$("#date").mask({ mask: "##/##/####", allowPartials: true });
Optionally, if you would like to execute a function once the mask has been completed, you can specify that function as an optional argument to the maskedinput method.
$("#date").mask({ mask: "##/##/####", completed: function(){
alert("You typed the following: " + this.val());
}
});
Opitionally, if you would like to use literal characters in your mask, which also happen to be characters used for mask definitions, you can escape the characters.
$("#date").mask({ mask: "##/##/#### \\?\\a\\\\", allowPartials: true });
Which will appear as __-____ ?a\ within the target element.
You can also supply your own mask definitions.
$.mask.definitions['~']='[+-]';
$("#eyescript").mask("~#.## ~#.## ###");
Requirements
- Definition for international, alphabetic characters. May require localization.
Options
- mask - Defines the mask that the plugin will use and apply to the selected element(s)
- placeholder - Defines the character that the plugin will use to indicate that input is required for a particular position.
- allowPartials - If true, the user is allowed to enter part of the data required to complete the mask. If false, the '?' character is used to indicate at which position the mask should allow partial input. If the '?' character is not included in the mask, the mask will disallow any partial input and the input element's value will reset to an empty string.
4 - Markup & Style:
4.1 Initial markup examples
No HTML or markup is written or appended to the page. The plugin modifies the value of the targeted input, or html of the targeted element.
4.2 Recommended transformed HTML markup
No HTML or markup is written or appended to the page. The plugin modifies the value of the targeted input, or html of the targeted element.
4.3 Accessibility recommendation
(Detailed recommendations for ARIA, HTML markup, CSS and javascript that will contribute to universal access and full section 508 accessibility for screen readers, mobile devices and any other devices)
4.4 CSS & Theme
The class "ui-mask" will be added to elements which this plugin is applied to. The class will be removed when the plugin is destroyed.
5 - Latest version of plugin:
Development Branch - http://jquery-ui.googlecode.com/svn/branches/labs/mask/demos/mask/default.html
Plugin Source - http://jquery-ui.googlecode.com/svn/branches/labs/mask/demos/mask/jquery.maskedinput.js
6 - Open issues being discussed
This plugin is currently being evaluated by the team.
Comments (14)
Andrew Powell said
at 5:42 pm on Mar 23, 2009
Per convo with Richard, some things that will be modified:
- Allow a user not to enter a mask on init, use mask('option', 'mask', '##') to apply a new mask.
- Move inline functions to _private methods.
- Remove var widget in favor of 'self'
Will most likely have these items wrapped up tonight, tomorrow at the latest.
Scott González said
at 6:26 pm on Mar 23, 2009
Alphabetic masks should support accented and other international characters. In a mask that only allows letters, you should be able to type González or Jörn.
Igor said
at 10:01 pm on Mar 23, 2009
Always had a problem with masked input: 99/99/9999 - it's not really a date format.
May be we should support limits for numeric inputs?
Andrew Powell said
at 10:10 pm on Mar 23, 2009
@ Scott - I'll do some digging tomorrow, but I don't know off the top of my head how to go about supporting a potentially vast amount of special unicode characters. There is the ability of the user to extend the list of definitions, and override the alphabetic regex used. But, yeah, it would be nice to support that. Please do lend a hand if you know how to support something like that.
@ Igor - Agreed. However, this plugin isn't intended to validate input, yet. (aside from the mask specified) That is perhaps something we can tie into the validator plugin at a later point.
Andrew Powell said
at 10:18 pm on Mar 23, 2009
Richard suggested that I add a class of 'ui-mask' to the element which the plugin was applied to.Should I also apply a class for focus and perhaps an incomplete (partial) mask content? Comments? Suggestions?
Todd Parker said
at 7:12 pm on Mar 24, 2009
This is cool and works really well. Nice work Andrew. Igor's question is interesting because there is some overlap here between the planned validation plugin and this. A masked input provides constraints to avoid entering to error conditions that validation would catch, but for dates that have some complexity on what is valid (31 is a valid day in January but not February) that could be handled (roughly) in a mask if you could say months can be values from 1-12, days 1-31 and years 2000-2030. This would at least limit the dates into the ballpark, but additional validation would need to be required for the Jan/Feb example. Is this possible with this now or do you only check for digits (0-9), alpha and other basic types, not numeric value ranges?
I do think that this mask feature should not impede accessibility, especially for screen readers. It probably isn't acceptable lose accessibility for such a fairly minor enhancement.
Igor said
at 10:02 pm on Mar 25, 2009
@ Todd - That's precisely the way of handling I've been thinking of: the idea that I can put the 31th of february is less striking than that I can put the 99th.
Andrew Powell said
at 5:24 am on Mar 26, 2009
I'm still going to assert that the role of this plugin is not validation. When the validation plugin is ready, we can certainly tie it into mask, optionally. There's a lot of focus on validation of a date, and I feel that it's misplaced. The mask plugin can be used for any, infinite number of formats and not just dates. If we validate one format (such as the demo'd date, which isnt even internationally standard) then we're going to have to provide a mechanism to validate all formats. That just isn't in scope at the moment, and should be part of the validation plugin.
For the moment, I would ask that discussion about validation be redirected to the validation page, and that we focus on the features in this plugin that are already present and the issues which need to be addressed, such as accessibility.
Richard, Scott G and others had some good comments about accessibility on the jquery-ui-dev thread; http://groups.google.com/group/jquery-ui-dev/browse_thread/thread/d2094163defbd29/c0eb5110345ecb36?lnk=gst&q=mask+demo#c0eb5110345ecb36
Before we speculate on what this will do to screen readers, we should have some definitive test results.
Scott González said
at 6:40 am on Mar 26, 2009
I'm with Andrew on the validation aspect, though I think what has been discussed can be accomplished if we allow inline set definitions:
$('#date').mask({ mask: '[0-1]#/[0-3]#/[1-2]###' });
Andrew Powell said
at 10:19 am on Mar 30, 2009
@ Richard, Scott
I have all of the suggestions and change requests completed an committed to the dev branch. Changing of the mask on the fly, and removing the mask (without destroying the instance) are now implemented and working. Changing of the placeholder on the fly is now also supported.
@ Scott
I'd appreciate some suggestions as far as supporting accented characters (basically unicode). I've done some reading and the most comprehensive coverage of that topic comes from a familiar source: http://www.regular-expressions.info/unicode.html. It looks like support for that in javascript has to be extremely specific to the characters you want to allow. In this situation, the user is going to have to modify the definitions manually. The demo demonstrates how to do this.
I'm still working on character classes. Still considering syntax and such; the implementation of the literals/escaping support was part of that.
@ All
The plugin has really progressed, and I'd like to start discussing what is yet required to get this into consideration for 1.8 :)
Andrew Powell said
at 10:20 am on Mar 30, 2009
Sorry, "character classes" == "inline set definitions". Mind is wandering today :)
Richard D. Worth said
at 11:08 am on May 14, 2009
@Andrew: I was just playing with this for a bit, and found the default behavior a bit odd. You mention the role of the plugin is not validation. If that's the case, is there a compelling reason to default allowPartials to false? I typed an area code into the phone number + extension demo field and pressed tab and was surprised when it cleared it. Then I found I had to enter the entire mask, including the five digit extension to get it to "take". Seems like a safer default would be to allow for partials, since the partial value that was entered (in this case the area code) was still entered with the help of the mask, and leave validation to another plugin. Of course, there would still be an option to set allowPartials to false, but I don't think it's the right default. What do you think?
Adam said
at 7:22 am on Jan 20, 2010
First off, nice work.
Accepting that mask is for more than just dates, I'm about to add to the dates discussion. I do think dates are one of the best uses of the mask function, simply because there is no internationally agreed format, so one must show the format to the user and make sure they follow it.
I'd like to be able to mask date formats such as 1/1/2010 (without forcing the user to 01/01/2010) while still allowing later days/months such as 31/12/2010. I.e., to mask a regexp of '[\d][\d]?/[\d][\d]?/[\d]{4}' In other words, to have variable lengths for a section, with restrictions after that. The behaviour I imagine in the first situation (1/1/2010) is that pressing the right arrow after "1" digit, or typing the "/" (or, for those who must use a mouse for everything, clicking after the "/") would move the cursor on to the second "section". If one instead typed two digits and then "/" it would also leave one at the start of the second "section", but pressing "/" a second time would move one to the third section
Example
Press: 1 <rightArrow> 1 / 2 0 1 0;
Result: 1/1/2010
Press: 1 1 3 / 2 0 1 0
Result: 11/3/2010
Press: 3 1 1 <rightArrow> 2 0 1 0
Result: 31/1/2010
Press: 31 1 2 2 0 1 0
Result: 31/12/2010
Press: 3 1 / 1 2 / 2 0 1 0
Result: 31/12/2010
Actually, while the example I have is a date I can see it being useful for telephone numbers (in an international context, where the length of the country code can be 1, 2 or 3 digits, area codes can vary in length, etc.). E.g. '\+[\d][\d]?[\d?] - [\d]*' would allow "+1 - 123456789" and "+44 - 123456789" and also "+358 - 123456789"
I know the focus just now is on getting the existing version in the next release, but wondered what folk thought of this - is it crazy/unusable or is it worth investigating (or, better yet, can you do it already with some cunning trick that I've missed? :) )
phazei said
at 2:07 am on Aug 18, 2010
Might I suggest taking a look at this for some ideas: http://www.meiocodigo.com/projects/meiomask/
I didn't see it mentioned here so I wasn't certain if anyone was aware of it.
There are some features it has that are useful, like some nice masking options for numbers, signed and not, that would be nice to include along with the "reverse" like a calculator. And the "reverse" input for numbers. MeioMask also includes a callbacks onValid, onInvalid, onOverflow which are convenient.
It also has a string function which works without an input where you can simply supply a string and a mask to it and it will return the masked string. Would be useful if say you were pulling an unformatted phone number and you wanted to format it before putting it somewhere.
Also, how does this demo with a value preset in a field, will the mask be applied?
You don't have permission to comment on this page.