# Inputmask 3.x
Copyright (c) 2010 - 2017 Robin Herbots Licensed under the MIT license ([http://opensource.org/licenses/mit-license.php](http://opensource.org/licenses/mit-license.php))
[![NPM Version][npm-image]][npm-url] [![Dependency Status][david-image]][david-url] [![devDependency Status][david-dev-image]][david-dev-url]
Inputmask is a javascript library which creates an input mask. Inputmask can run against vanilla javascript, jQuery and jqlite.
An inputmask helps the user with the input by ensuring a predefined format. This can be useful for dates, numerics, phone numbers, ...
Highlights:
- easy to use
- optional parts anywere in the mask
- possibility to define aliases which hide complexity
- date / datetime masks
- numeric masks
- lots of callbacks
- non-greedy masks
- many features can be enabled/disabled/configured by options
- supports readonly/disabled/dir="rtl" attributes
- support data-inputmask attribute(s)
- alternator-mask
- regex-mask
- dynamic-mask
- preprocessing-mask
- JIT-masking
- value formatting / validating without input element
- AMD/CommonJS support
- dependencyLibs: vanilla javascript, jQuery, jqlite
- <strike>[Android support](README_android.md)</strike>
Demo page see [http://robinherbots.github.io/Inputmask](http://robinherbots.github.io/Inputmask)
[![donate](https://www.paypalobjects.com/en_US/i/btn/btn_donate_SM.gif)](https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=ZNR3EB6JTMMSS)
## Setup
### dependencyLibs
Inputmask can run against different javascript libraries.
You can choose between:
- inputmask.dependencyLib (vanilla)
- inputmask.dependencyLib.jquery
- inputmask.dependencyLib.jqlite
- .... (others are welcome)
### Classic web with <script\> tag
Include the js-files which you can find in the `dist` folder.
If you want to include the Inputmask and all extensions. (with jQuery as dependencylib)
```html
<script src="jquery.js"></script>
<script src="dist/jquery.inputmask.bundle.js"></script>
<script src="dist/inputmask/phone-codes/phone.js"></script>
<script src="dist/inputmask/phone-codes/phone-be.js"></script>
<script src="dist/inputmask/phone-codes/phone-ru.js"></script>
```
For individual extensions. (with jQuery as dependencylib)
```html
<script src="jquery.js"></script>
<script src="dist/inputmask/inputmask.js"></script>
<script src="dist/inputmask/inputmask.extensions.js"></script>
<script src="dist/inputmask/inputmask.numeric.extensions.js"></script>
<script src="dist/inputmask/inputmask.date.extensions.js"></script>
<script src="dist/inputmask/inputmask.phone.extensions.js"></script>
<script src="dist/inputmask/jquery.inputmask.js"></script>
<script src="dist/inputmask/phone-codes/phone.js"></script>
<script src="dist/inputmask/phone-codes/phone-be.js"></script>
<script src="dist/inputmask/phone-codes/phone-ru.js"></script>
```
For individual extensions. (with vanilla dependencylib)
```html
<script src="dist/inputmask/dependencyLibs/inputmask.dependencyLib.js"></script>
<script src="dist/inputmask/inputmask.js"></script>
<script src="dist/inputmask/inputmask.extensions.js"></script>
<script src="dist/inputmask/inputmask.numeric.extensions.js"></script>
<script src="dist/inputmask/inputmask.date.extensions.js"></script>
<script src="dist/inputmask/inputmask.phone.extensions.js"></script>
<script src="dist/inputmask/phone-codes/phone.js"></script>
<script src="dist/inputmask/phone-codes/phone-be.js"></script>
<script src="dist/inputmask/phone-codes/phone-ru.js"></script>
```
If you like to automatically bind the inputmask to the inputs marked with the data-inputmask- ... attributes you may also want to include the inputmask.binding.js
```html
<script src="dist/inputmask/bindings/inputmask.binding.js"></script>
```
### webpack
#### Install the package
```
npm install inputmask --save-dev
```
#### In your modules
If you want to include the Inputmask and all extensions.
```
var Inputmask = require('inputmask');
//es6
import Inputmask from "inputmask";
```
For individual extensions.
Every extension exports the Inputmask, so you only need to import the extensions.
See example.
```
require("inputmask/dist/inputmask/inputmask.numeric.extensions");
var Inputmask = require("inputmask/dist/inputmask/inputmask.date.extensions");
//es6
import "inputmask/dist/inputmask/inputmask.numeric.extensions";
import Inputmask from "inputmask/dist/inputmask/inputmask.date.extensions";
```
#### Selecting the dependencyLib
By default the vanilla dependencyLib is used. You can select another dependency
by creating an alias in the webpack.config.
```
resolve: {
alias: {
"./dependencyLibs/inputmask.dependencyLib": "./dependencyLibs/inputmask.dependencyLib.jquery"
}
},
```
## Usage
### via Inputmask class
```javascript
var selector = document.getElementById("selector");
var im = new Inputmask("99-9999999");
im.mask(selector);
//or
Inputmask({"mask": "(999) 999-9999", .... other options .....}).mask(selector);
Inputmask("9-a{1,3}9{1,3}").mask(selector);
Inputmask("9", { repeat: 10 }).mask(selector);
```
### via jquery plugin
```javascript
$(document).ready(function(){
$(selector).inputmask("99-9999999"); //static mask
$(selector).inputmask({"mask": "(999) 999-9999"}); //specifying options
$(selector).inputmask("9-a{1,3}9{1,3}"); //mask with dynamic syntax
});
```
### via data-inputmask attribute
```html
<input data-inputmask="'alias': 'date'" />
<input data-inputmask="'mask': '9', 'repeat': 10, 'greedy' : false" />
<input data-inputmask="'mask': '99-9999999'" />
```
```javascript
$(document).ready(function(){
$(":input").inputmask();
or
Inputmask().mask(document.querySelectorAll("input"));
});
```
#### Any option can also be passed through the use of a data attribute. Use data-inputmask-<**_the name of the option_**>="value"
```html
<input id="example1" data-inputmask-clearmaskonlostfocus="false" />
<input id="example2" data-inputmask-regex="[a-za-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+(?:\.[a-zA-Z0-9!#$%&'*+/=?^_`{|}~-]+)*@(?:[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?\.)+[a-zA-Z0-9](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?" />
```
```javascript
$(document).ready(function(){
$("#example1").inputmask("99-9999999");
$("#example2").inputmask();
});
```
### Allowed HTML-elements
- `<input type="text">`
- `<input type="tel">`
- `<input type="password">`
- `<div contenteditable="true">` (and all others supported by contenteditable)
- `<textarea>`
- any html-element (mask text content or set maskedvalue with jQuery.val)
The allowed input types are defined in the supportsInputType option. Also see ([input-type-ref])
### Default masking definitions
- `9` : numeric
- `a` : alphabetical
- `*` : alphanumeric
There are more definitions defined within the extensions.<br>You can find info within the js-files or by further exploring the options.
## Masking types
### Static masks
These are the very basic of masking. The mask is defined and will not change during the input.
```javascript
$(document).ready(function(){
$(selector).inputmask("aa-9999"); //static mask
$(selector).inputmask({mask: "aa-9999"}); //static mask
});
```
### Optional masks
It is possible to define some parts in the mask as optional. This is done by using [ ].
Example:
```javascript
$('#test').inputmask('(99) 9999[9]-9999');
```
This mask wil allow input like `(99) 99999-9999` or `(99) 9999-9999`.
Input => 12123451234 mask => (12) 12345-1234 (trigger complete)<br>
Input => 121234-1234 mask => (12) 1234-1234 (trigger complete)<br>
Input => 1212341234 mask => (12) 12341-234_ (trigger incomplete)
#### skipOptionalPartCharacter
As an extra there is another configurable character which is used to skip an optional part in the mask.
```javascript
skipOptionalPartCharacter: " "
```
Input => 121234 1234 mask => (12) 1234-1234 (trigger complete)
When `clearMaskOnLostFocus: true` is set in the options (default), the mask will clear out the optiona