Masked Input Plugin

spacer Download Latest (1.4)
  • Uncompressed
  • Minified
This is a masked input plugin for the jQuery javascript library. 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). It has been tested on Internet Explorer, Firefox, Safari, Opera, and Chrome. 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 - Represents an alpha character (A-Z,a-z)
  • 9 - Represents a numeric character (0-9)
  • * - Represents an alphanumeric character (A-Z,a-z,0-9)
  • Usage
  • Demo
  • Changelog
  • License
First, include the jQuery and masked input javascript files.
<script src="/img/spacer.gif"> 
Next, call the mask function for those items you wish to have masked.
jQuery(function($){
   $("#date").mask("99/99/9999",{placeholder:"mm/dd/yyyy"});
   $("#phone").mask("(999) 999-9999");
   $("#tin").mask("99-9999999");
   $("#ssn").mask("999-99-9999");
});
Optionally, if you are not satisfied with the underscore ('_') character as a placeholder, you may pass an optional argument to the maskedinput method.
jQuery(function($){
   $("#product").mask("99/99/9999",{placeholder:" "});
});
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.
jQuery(function($){
   $("#product").mask("99/99/9999",{completed:function(){alert("You typed the following: "+this.val());}});
});
You can now supply your own mask definitions.
jQuery(function($){
   $.mask.definitions['~']='[+-]';
   $("#eyescript").mask("~9.99 ~9.99 999");
});
You can have part of your mask be optional. Anything listed after '?' within the mask is considered optional user input. The common example for this is phone number + optional extension.
jQuery(function($){
   $("#phone").mask("(999) 999-9999? x99999");
});
If your requirements aren't met by the predefined placeholders, you can always add your own. For example, maybe you need a mask to only allow hexadecimal characters. You can add your own definition for a placeholder, say 'h', like so: $.mask.definitions['h'] = "[A-Fa-f0-9]"; Then you can use that to mask for something like css colors.
jQuery(function($){
   $("#phone").mask("#hhhhhh");
});
By design, this plugin will reject input which doesn't complete the mask. You can bypass this by using a '?' character at the position where you would like to consider input optional. For example, a mask of "(999) 999-9999? x99999" would require only the first 10 digits of a phone number with extension being optional.
The following example is a demonstration from the usage tab.
Date 99/99/9999
Phone (999) 999-9999
Phone + Ext (999) 999-9999? x99999
Tax ID 99-9999999
SSN 999-99-9999
Product Key a*-999-a999
Eye Script ~9.99 ~9.99 999
1.3.1Bugfixes
  • jQuery 1.9 compatibility.
  • Fixed browser lockup when window loses focus.
  • Android issues.
  • No longer preventing event bubbling.
  • Making sure we call completed handler when pasting a value.
  • Fixed bug trying to set caret on hidden elements.
  • Fixed cursor positioning bug related to bounds check.
1.3Bugfixes
  • Fixed completed callback bug.
  • Fixed IE bug requiring charAt() instead of array notation to access char within string.
  • Fixed delete key handling with cursor at literal character.
  • Fixed infinite focus loop bug with multiple masked inputs on a page.
  • Fixed raw value returning mask placeholders when input empty.
Enhancements
  • Now gracefully handle it when mask() gets called multiple times by calling unmask() on behalf of the user.
1.2.2 Bugfixes
  • Fixed bug which blocked apple meta key. This was keeping copy and paste via keyboard shortcut from working on Mac.
  • Fixed bug that caused mask literals to be pushed into the mask placeholder positions when verifying the data.
  • Fixed bug that prevented user input from completing when mask ended in mask literal.
Changes
  • Changed behavior on focus to select all text if focusing on a completed mask.
  • No more masking on readonly inputs.
  • Changed escape behavior to put the input back to the original value instead of just blanking the text.
  • Increased range of accepted characters for input.
1.2.1
  • BREAKING CHANGE: Removed deprecated $.mask.addPlaceholder method. Use the "$.mask.definitions['']="";" syntax instead. I said I was going to do this on the last release and now seems just as good a time as any.
  • BREAKING CHANGE: Removed "allowPartial" option in favor of new mask syntax I'll describe below. A discussion and code exchange with Michael Bray inspired this change. I hate that it's a breaking change, but the new way makes a lot more sense.
  • New mask syntax option '?'. Anything listed after '?' within the mask is considered optional user input. The common example for this is phone number + optional extension. The new syntax will look like this: "(999) 999-9999? x99999"
  • I got rid of the awkward input behavior where users typed over top of existing input. The plugin acted like a word processor Insert mode. This has always agrivated me, so now the input shifts on input and backspace/delete.
  • Now calling .change() on blur if the value has changed since the plugin prevents the change event from being fired naturally.
  • Pasting incomplete test no longer wipes the input. Instead, the cursor is just placed where the input leaves off.
  • Fixed backspace detection for iPhone. Plugin is now iPhone compatible.
  • Fixed pasting bug when mask starts with a literal and caret position is on the literal character.
1.2
  • Paste support for more browsers. It should now work in IE7, Firefox 3, Safari, Chrome, and Opera.
  • Fixed backspace bug in Opera. I had originally put in special handling for Opera to get past a bug that appears to be fixed in current releases. This code is now removed.
  • Calling .mask() with no arguments will now return the value of the input without the literals.
  • Added option "allowPartial" that will allow partial input to remain when focus is lost.
  • Exposed the hash table of the mask definitions directly to replace the $.mask.addPlaceholder() method. The old method remains for now, but will be removed in a future relase. You should now add custom mask definitions by "$.mask.definitions[char]=regex;"
  • Code refactoring and house cleaning. I made things more jQuery like and removed some crufty code in the process. The end result is better organization to build on for future enhancements.
1.1.4
  • Fixed a bug where mask characters that match the criteria for the first placeholder(s) would end up trashing the user input. Thanks to Steve Davis for finding and fixing this one.
1.1.3
  • Fixed a bug where the buffer wasn't being cleared properly, causing characters that had been shifted to be duplicated.
1.1.2
  • Fixed a bug in Mac Firefox with backspacing.
  • Fixed a bug where delete at end of mask produced an extra placeholder character.
  • Exposed the caret positioning and retrieval methods as a jQuery function extension. You can now call $().caret() to get a caret position and $().caret(start [,end]) to set a caret position.
1.1.1
  • Fixed a bug introduced with the code changes that prevented IE from working at all.
1.1
  • NEW FEATURE: unmask() method to remove masking for a previously masked input.
  • Safari cursor position fix.
  • Cursor position behavior change: Cursor goes to the end of the input on a completed input. Cursor goes to the first placeholder position on a blank input.
  • Fixed improper escaping of certain mask characters.
  • Code refactoring to reduce size and complexity.
1.0
  • Cosmetic code cleanup
Release Candidate 3
  • BREAKING CHANGE: The mask function has been changed to more closely match the style of the jQuery library. Instead of calling .maskedinput(), you will need to call .mask(). Additionally the .AddMaskDefinition() has been moved to a namespace and renamed. Instead, you should make a call to .mask.addPlaceholder().
  • Fixed a bug where the buffer was wiped when text was selected and a non-typeable character was pressed.
  • Fixed a bug where the buffer was not cleared, but the text was when pressing the escape key.
  • More code cleanup.
Release Candidate 2
  • Now supports user defined placeholder characters by calling "$.AddMaskDefinition(char,regex)" Please see the Eye Prescription example above.
  • Fixed a bug where backspace from the first character position deleted the mask.
  • General code cleanup.
Release Candidate 1a
  • Corrected the kludgey syntax for the optional mask completed function. You no longer need to pass an argument to your function to gain access to the input making the call. You can now simply reference "this". Please see the above corrected example.
Release Candidate 1
  • Fixed a Safari issue where backspace deleted wrong characters and messed up cursor position.
  • Fixed an issue where pre-filled input (value="something") was deleted on focus.
Masked Input Beta 2a
  • Fixed an issue with the mask disappearing on focus when the input box has no data.
Beta 2
  • BREAKING CHANGE: If you were using the optional placeholder argument, you will need to change it to a hashmap syntax. Please see the example above for reference.
  • Fixed an issue with pasted values not persisting after a blur/focus.
  • Added an optional user defined function to execute when the mask has been completed. I'm using this for my personal projects to advance focus to another area of the form, but this could also be used to validate the value inside the input box. Please see example above.
  • Fixed the naming convention to conform to the jQuery standard of jquery.pluginname.js
  • Moved the project files to a more logical location on the web server.
Beta 1
  • Fixed issues with allowing punctuation on number masks.
  • Added validation cleanup of text. Example: pasting in "123-456-7890" into a "(999) 999-9999" mask should format correctly.
  • Added validation on paste events for Mozilla and IE.
Alpha 1
  • Initial Release
Copyright (c) 2007-2014 Josh Bush (digitalbush.com)

Permission is hereby granted, free of charge, to any person
obtaining a copy of this software and associated documentation
files (the "Software"), to deal in the Software without
restriction, including without limitation the rights to use,
copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following
conditions:

The above copyright notice and this permission notice shall be
included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
OTHER DEALINGS IN THE SOFTWARE.

gipoco.com is neither affiliated with the authors of this page nor responsible for its contents. This is a safe-cache copy of the original web site.