Input Mask
Bootstrap 5 Input Mask plugin
The Input Mask is a custom directive which allows to set a predefined format of forms.
Responsive Input Mask directive for the latest Bootstrap 5. Set a predefined format of forms. Phone number, special characters, clear incomplete & other examples.Note: Read the API tab to find all available options and advanced customization
Note: Currently, the plugin is only compatible with the basic MDB package imported in UMD format. More about import MDB formats.
Basic example
Input Mask comes with three predefined masks directives:
- a - Alpha characters (default: A-Z,a-z)
- 9 - Numeric characters (0-9)
- * - Alphanumeric characters (A-Z,a-z,0-9)
To initialize Input Mask on an element, add the data-mdb-input-mask-init
attribute and data-mdb-input-mask
attribute with mask format to the input.
<div class="form-outline" data-mdb-input-init>
<input type="text" id="basic-example" class="form-control" data-mdb-input-mask-init
data-mdb-input-mask="aaa999***" />
<label class="form-label" for="basic-example">Basic example</label>
</div>
Clear incomplete
By default, Input Mask will clear incomplete input value on blur. Turn this behavior off with
data-mdb-clear-incomplete="false"
.
<div class="form-outline" data-mdb-input-init>
<input type="text" id="clear-incomplete" class="form-control" data-mdb-input-mask-init data-mdb-input-mask="99-999-99" data-mdb-clear-incomplete="false"/>
<label class="form-label" for="clear-incomplete">Clear incomplete</label>
</div>
Custom mask
Define custom mask with data-mdb-custom-mask
for mask symbol and
data-mdb-custom-validator
with custom mask regex pattern. Example below will only
allow abc
letters to be typed for p
mask.
<div class="form-outline" data-mdb-input-init>
<input type="text" id="custom-mask" class="form-control" data-mdb-input-mask-init data-mdb-input-mask="999ppp999" data-mdb-custom-mask="p" data-mdb-custom-validator="[abc]"/>
<label class="form-label" for="custom-mask">Custom mask</label>
</div>
You can also set more than one mask by passing multiple characters separated by comma to
data-mdb-custom-mask
, and their corresponding validators separated by comma to
data-mdb-custom-validator
<div class="form-outline" data-mdb-input-init>
<input type="text" id="custom-masks" class="form-control" data-mdb-input-mask="pppbbbccc" data-mdb-custom-mask="p,b,c" data-mdb-custom-validator="[abc],[1-2],[^a-c]"/>
<label class="form-label" for="custom-masks">Custom mask</label>
</div>
Special characters
Input Mask allows any non-alphanumeric character to be used inside the
data-mdb-input-mask
. Those characters will be hardcoded into the input during
typing.
<div class="form-outline" data-mdb-input-init>
<input type="text" id="phone" class="form-control" data-mdb-input-mask-init data-mdb-input-mask="+48 999-999-999"/>
<label class="form-label" for="phone">Phone number with country code</label>
</div>
<div class="form-outline" data-mdb-input-init>
<input type="text" id="book" class="form-control" data-mdb-input-mask-init data-mdb-input-mask="ISBN 0-99999-999-0"/>
<label class="form-label" for="book">Book number</label>
</div>
Mask placeholder
Set placeholder for mask while typing with data-mdb-mask-placeholder="true"
.
Default placeholder is an underscore sign _
. Change it with
data-mdb-char-placeholder
. You can use single character or define placeholder for
whole mask.
<div class="form-outline" data-mdb-input-init>
<input type="text" id="defaultPlaceholder" class="form-control" data-mdb-input-mask-init data-mdb-input-mask="(99)-999-99" data-mdb-mask-placeholder="true"/>
<label class="form-label" for="defaultPlaceholder">Default placeholder</label>
</div>
<div class="form-outline" data-mdb-input-init>
<input type="text" id="customPlaceholder" class="form-control" data-mdb-input-mask-init data-mdb-input-mask="99/99/9999 99:99" data-mdb-mask-placeholder="true" data-mdb-char-placeholder="dd/mm/yyyy hh:mm"/>
<label class="form-label" for="customPlaceholder">Custom placeholder</label>
</div>
Phone number input mask
Input mask can be used with Autocomplete to create an international phone number input. When user selects a country, input mask will be updated with mask pattern used in selected country.
<div class="m-3">
<div class="d-inline-block" style="width:5rem">
<div id="customItem" class="form-outline" data-mdb-input-init data-mdb-list-height="290">
<input type="text" id="form1" class="form-control" />
<label class="form-label" for="form1">Code</label>
</div>
</div>
<div class="d-inline-block">
<div class="form-outline" data-mdb-input-init>
<input type="text" id="inputMask" class="form-control" data-mdb-input-mask-init />
<label class="form-label" for="inputMask">Phone Number</label>
</div>
</div>
</div>
const customItem = document.querySelector('#customItem');
const data = [
{
code: '86',
flag: 'china',
inputMask: '(99) 9999999'
},
{
code: '33',
flag: 'france',
inputMask: '99 99 99 99 99'
},
{
code: '44',
flag: 'united-kingdom',
inputMask: '9999 999 999'
},
{
code: '1',
flag: 'united-states',
inputMask: '(999) 999-9999'
},
{
code: '58',
flag: 'venezuela',
inputMask: ' 999-9999999'
},
];
const dataFilter = (value) =>
data.filter((item) =>
item.code.toString().includes(value.toString())
)
new mdb.Autocomplete(customItem, {
filter: dataFilter,
displayValue: (value) => value.code,
itemContent: (result) => {
return `
<div class="d-flex justify-content-between flex-fill">
<div><i class="flag flag-${result.flag}"></i></div>
<div class="flex-fill text-center">${result.code}</div>
</div>
`;
},
});
const inputMaskEl = document.querySelector('#inputMask');
let inputMaskInstance;
customItem.addEventListener('itemSelect.mdb.autocomplete', (e) => {
const inputMaskPattern = e.value.inputMask;
if (inputMaskInstance) {
inputMaskEl.value = "";
inputMaskInstance.dispose();
}
inputMaskInstance = new InputMask(inputMaskEl, {
maskPlaceholder: true,
inputMask: inputMaskPattern,
clearIncomplete: false
});
});
Input Mask - API
Import
import InputMask from 'mdb-inputmask';
Usage
Via data attributes
Using the Input Mask plugin doesn't require any additional JavaScript code - simply add
data-mdb-input-mask-init
attribute to
input
tag
and use other data attributes to set all options.
<div class="form-outline" data-mdb-input-init>
<input type="text" data-mdb-input-mask-init data-mdb-input-mask="aaa999***"/>
</div>
Via JavaScript
const options = {
inputMask: "aaa999***"
}
const inputElement = document.getElementById('js-usage-example');
const instance = new InputMask(inputElement, options)
Via jQuery
Note: By default, MDB does not include jQuery and you have to add it to the project on your own.
$(document).ready(() => {
$('#jquery-usage-example').InputMask();
});
Options
Options can be passed via data attributes or JavaScript. For data attributes, append the option name to
data-mdb-
, as in data-mdb-input-mask=""
.
Name | Type | Default | Description |
---|---|---|---|
inputMask
|
String | "" |
Defines Input Mask pattern to be added to input element |
charPlaceholder |
String | "_" |
Placeholder character for covered characters in mask. Visible while typing only when
maskPlaceholder is set to true
|
maskPlaceholder |
Boolean | false |
Sets charPlaceholder on or off |
inputPlaceholder |
Boolean | true |
Shows information about the mask pattern on inactive input |
clearIncomplete |
Boolean | true |
Clear incomplete input value on blur |
customMask |
String | "" |
Defines character to be used as custom mask. Allows multiple characters to be passed, separated by comma |
customValidator |
String | "" |
Regex pattern to match characters in mask. Allows multiple validators corespondiing to their masks to be passed, separated by comma. |
Methods
Name | Parameters | Description | Example |
---|---|---|---|
dispose
|
Removes the InputMask instance. |
instance.dispose()
|
|
getInstance
|
element | Static method which allows to get the InputMask instance associated with a DOM element. |
InputMask.getInstance(element)
|
const inputElement = document.getElementById('inputmask-example');
const instance = InputMask.getInstance(inputElement);
instance.dispose();
Events
Name | Description |
---|---|
valueChanged.mdb.inputMask
|
Emitted when InputMask instance element receives new value. Returns
value object inside event callback with input typed characters.
|
completed.mdb.inputMask
|
Emitted when InputMask instance element receives completed mask pattern value. Returns
value object inside event callback with completed value.
|
const inputElement = document.getElementById('inputmask-example');
inputElement.addEventListener('completed.mdb.inputMask', () => {
alert('Mask input completed!');
});