DevExtreme jQuery/JS - Specify a Mask for the Input

A mask defines a pattern for the TextBox value. You can specify the mask using the mask option. 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.common.css';
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.common.css';
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 option, while its unmasked equivalent goes to the value option. If you use jQuery, you can get the value of either of these options using the option(optionName) method.

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

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

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.common.css';
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.common.css';
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 option.

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.common.css';
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.common.css';
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