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!');
          });