JavaScript/jQuery TextBox - Specify a Mask for the Input

A mask defines a pattern for the TextBox value. You can specify the mask using the mask property. A mask can contain the following elements.

Masking Element Description
0 A digit.
9 A digit or a space.
# A digit, a space, "+" or "-" sign.
L A literal.
C Any character except space.
c Any character.
A An alphanumeric.
a An alphanumeric or a space.

You can also define custom masking elements using the maskRules object. Each field of this object defines a single masking element.

jQuery
JavaScript
$(function() {
    $("#textBoxContainer").dxTextBox({
        mask: "SFFFFHN",
        maskRules: {
            // a single character
            S: '$',

            // a regular expression
            H: /[0-9A-F]/,

            // an array of characters
            N: ['$', '%', '&', '@'],

            // a function
            F: function (char) {
                return char == char.toUpperCase();
            }
        }
    });
});
Angular
HTML
TypeScript
<dx-text-box
    mask="SFFFFHN"
    [maskRules]="maskRules">
</dx-text-box>
import { DxTextBoxModule } from "devextreme-angular";
// ...
export class AppComponent {
    maskRules = {
        // a single character
        S: '$',

        // a regular expression
        H: /[0-9A-F]/,

        // an array of characters
        N: ['$', '%', '&', '@'],

        // a function
        F: function (char) {
            return char == char.toUpperCase();
        }
    };
}
@NgModule({
    imports: [
        // ...
        DxTextBoxModule
    ],
    // ...
})
Vue
<template>
    <DxTextBox
        :mask-rules="maskRules"
        mask="SFFFFHN"
    />
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import { DxTextBox } from 'devextreme-vue/text-box';

export default {
    components: {
        DxTextBox
    },
    data() {
        return {
            maskRules: {
                // a single character
                S: '$',

                // a regular expression
                H: /[0-9A-F]/,

                // an array of characters
                N: ['$', '%', '&', '@'],

                // a function
                F: function(char) {
                    return char == char.toUpperCase();
                }
            }
        };
    }
}
</script>
React
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import { TextBox } from 'devextreme-react/text-box';

const maskRules = {
    // a single character
    S: '$',

    // a regular expression
    H: /[0-9A-F]/,

    // an array of characters
    N: ['$', '%', '&', '@'],

    // a function
    F: (char) => {
        return char == char.toUpperCase();
    }
}

class App extends React.Component {
    render() {
        return (
            <TextBox
                maskRules={maskRules}
                mask="SFFFFHN"
            />
        );
    }
}

export default App;

The masked value goes to the read-only text property, while its unmasked equivalent goes to the value property.

jQuery

You can get the value of either of these properties using the option(optionName) method.

JavaScript
const maskedValue = $("#textBoxContainer").dxTextBox("option", "text");
const unmaskedValue = $("#textBoxContainer").dxTextBox("option", "value");

By default, the UI component uses underscores to designate blanks in the masked value. You can specify another symbol using the maskChar property.

jQuery
JavaScript
$(function() {
    $("#textBoxContainer").dxTextBox({
        mask: "+1 (200) 000-0000",
        maskChar: "‒"
    });
});
Angular
HTML
TypeScript
<dx-text-box
    mask="+1 (200) 000-0000"
    maskChar="‒">
</dx-text-box>
import { DxTextBoxModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTextBoxModule
    ],
    // ...
})
Vue
<template>
    <DxTextBox
        mask="+1 (200) 000-0000"
        mask-char="‒"
    />
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import { DxTextBox } from 'devextreme-vue/text-box';

export default {
    components: {
        DxTextBox
    }
}
</script>
React
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import { TextBox } from 'devextreme-react/text-box';

class App extends React.Component {
    render() {
        return (
            <TextBox
                mask="+1 (200) 000-0000"
                maskChar="‒"
            />
        );
    }
}

export default App;

If the input value does not match the mask, the TextBox displays an error message specified by the maskInvalidMessage property.

jQuery
JavaScript
$(function() {
    $("#textBoxContainer").dxTextBox({
        mask: "+1 (200) 000-0000",
        maskInvalidMessage: "The input value does not match the mask"
    });
});
Angular
HTML
TypeScript
<dx-text-box
    mask="+1 (200) 000-0000"
    maskInvalidMessage="The input value does not match the mask">
</dx-text-box>
import { DxTextBoxModule } from "devextreme-angular";
// ...
export class AppComponent {
    // ...
}
@NgModule({
    imports: [
        // ...
        DxTextBoxModule
    ],
    // ...
})
Vue
<template>
    <DxTextBox
        mask="+1 (200) 000-0000"
        mask-invalid-message="The input value does not match the mask"
    />
</template>

<script>
import 'devextreme/dist/css/dx.light.css';

import { DxTextBox } from 'devextreme-vue/text-box';

export default {
    components: {
        DxTextBox
    }
}
</script>
React
import React from 'react';
import 'devextreme/dist/css/dx.light.css';

import { TextBox } from 'devextreme-react/text-box';

class App extends React.Component {
    render() {
        return (
            <TextBox
                mask="+1 (200) 000-0000"
                maskInvalidMessage="The input value does not match the mask"
            />
        );
    }
}

export default App;
See Also