InputMask

InputMask is used to enter input in a certain format such as numeric, date, currency, email and phone.

Usage#

import { useMask } from '@primereact/hooks/use-mask';

const mask = useMask();

Examples#

Basic#

basic-demo

'use client';
import { useMask, type UseMaskChangeEvent } from '@primereact/hooks';
import { InputText, type InputTextInstance } from '@primereact/ui/inputtext';
import * as React from 'react';

export default function BasicDemo() {
    const [value, setValue] = React.useState('');
    const [target, setTarget] = React.useState<InputTextInstance | null>(null);
    const setInputRef = React.useCallback((instance: InputTextInstance | null) => {
        setTarget(instance);
    }, []);

    const { onMaskInput, onMaskKeyDown, onMaskKeyPress, onMaskFocus, onMaskBlur, onMaskPaste } = useMask({
        mask: '99-999999',
        onMaskChange: (event: UseMaskChangeEvent) => setValue(event.value ?? ''),
        target
    });

    return (
        <div className="flex justify-center">
            <InputText
                ref={setInputRef}
                value={value}
                placeholder="99-999999"
                onInput={onMaskInput}
                onKeyDown={onMaskKeyDown}
                onKeyPress={onMaskKeyPress}
                onFocus={onMaskFocus}
                onBlur={onMaskBlur}
                onPaste={onMaskPaste}
            />
        </div>
    );
}

Format Patterns#

Mask format can be a combination of the following definitions; a for alphabetic characters, 9 for numeric characters and * for alphanumberic characters. In addition, formatting characters like ( , ) , - are also accepted.

SSN

Phone

Serial

mask-demo

'use client';
import { useMask, type UseMaskChangeEvent } from '@primereact/hooks';
import { InputText, type InputTextInstance } from '@primereact/ui/inputtext';
import { Label } from '@primereact/ui/label';
import * as React from 'react';

export default function MaskDemo() {
    const [value1, setValue1] = React.useState('');
    const [value2, setValue2] = React.useState('');
    const [value3, setValue3] = React.useState('');
    const [target1, setTarget1] = React.useState<InputTextInstance | null>(null);
    const [target2, setTarget2] = React.useState<InputTextInstance | null>(null);
    const [target3, setTarget3] = React.useState<InputTextInstance | null>(null);
    const setInputRef1 = React.useCallback((instance: InputTextInstance | null) => {
        setTarget1(instance);
    }, []);
    const setInputRef2 = React.useCallback((instance: InputTextInstance | null) => {
        setTarget2(instance);
    }, []);
    const setInputRef3 = React.useCallback((instance: InputTextInstance | null) => {
        setTarget3(instance);
    }, []);

    // SSN Mask
    const {
        onMaskInput: onMaskInput1,
        onMaskKeyDown: onMaskKeyDown1,
        onMaskKeyPress: onMaskKeyPress1,
        onMaskFocus: onMaskFocus1,
        onMaskBlur: onMaskBlur1,
        onMaskPaste: onMaskPaste1
    } = useMask({
        mask: '999-99-9999',
        onMaskChange: (event: UseMaskChangeEvent) => setValue1(event.value ?? ''),
        target: target1
    });

    // Phone Mask
    const {
        onMaskInput: onMaskInput2,
        onMaskKeyDown: onMaskKeyDown2,
        onMaskKeyPress: onMaskKeyPress2,
        onMaskFocus: onMaskFocus2,
        onMaskBlur: onMaskBlur2,
        onMaskPaste: onMaskPaste2
    } = useMask({
        mask: '(999) 999-9999',
        onMaskChange: (event: UseMaskChangeEvent) => setValue2(event.value ?? ''),
        target: target2
    });

    // Serial Mask
    const {
        onMaskInput: onMaskInput3,
        onMaskKeyDown: onMaskKeyDown3,
        onMaskKeyPress: onMaskKeyPress3,
        onMaskFocus: onMaskFocus3,
        onMaskBlur: onMaskBlur3,
        onMaskPaste: onMaskPaste3
    } = useMask({
        mask: 'a*-999-a999',
        onMaskChange: (event: UseMaskChangeEvent) => setValue3(event.value ?? ''),
        target: target3
    });

    return (
        <div className="flex flex-wrap gap-4">
            <div className="flex-auto">
                <Label htmlFor="ssn" className="mb-2">
                    SSN
                </Label>
                <InputText
                    ref={setInputRef1}
                    value={value1}
                    id="ssn"
                    placeholder="999-99-9999"
                    fluid
                    onInput={onMaskInput1}
                    onKeyDown={onMaskKeyDown1}
                    onKeyPress={onMaskKeyPress1}
                    onFocus={onMaskFocus1}
                    onBlur={onMaskBlur1}
                    onPaste={onMaskPaste1}
                />
            </div>

            <div className="flex-auto">
                <Label htmlFor="phone" className="mb-2">
                    Phone
                </Label>
                <InputText
                    ref={setInputRef2}
                    value={value2}
                    id="phone"
                    placeholder="(999) 999-9999"
                    fluid
                    onInput={onMaskInput2}
                    onKeyDown={onMaskKeyDown2}
                    onKeyPress={onMaskKeyPress2}
                    onFocus={onMaskFocus2}
                    onBlur={onMaskBlur2}
                    onPaste={onMaskPaste2}
                />
            </div>

            <div className="flex-auto">
                <Label htmlFor="serial" className="mb-2">
                    Serial
                </Label>
                <InputText
                    ref={setInputRef3}
                    value={value3}
                    id="serial"
                    placeholder="a*-999-a999"
                    fluid
                    onInput={onMaskInput3}
                    onKeyDown={onMaskKeyDown3}
                    onKeyPress={onMaskKeyPress3}
                    onFocus={onMaskFocus3}
                    onBlur={onMaskBlur3}
                    onPaste={onMaskPaste3}
                />
            </div>
        </div>
    );
}

Optional#

When the input does not complete the mask definition, it is cleared by default. Use autoClear option to control this behavior. In addition, ? is used to mark anything after the question mark optional.

optional-demo

'use client';
import { useMask, type UseMaskChangeEvent } from '@primereact/hooks';
import { InputText, type InputTextInstance } from '@primereact/ui/inputtext';
import * as React from 'react';

export default function OptionalDemo() {
    const [value, setValue] = React.useState('');
    const [target, setTarget] = React.useState<InputTextInstance | null>(null);
    const setInputRef = React.useCallback((instance: InputTextInstance | null) => {
        setTarget(instance);
    }, []);

    const { onMaskInput, onMaskKeyDown, onMaskKeyPress, onMaskFocus, onMaskBlur, onMaskPaste } = useMask({
        mask: '(999) 999-9999? x99999',
        onMaskChange: (event: UseMaskChangeEvent) => setValue(event.value ?? ''),
        target
    });

    return (
        <div className="flex justify-center">
            <InputText
                ref={setInputRef}
                placeholder="(999) 999-9999? x99999"
                value={value}
                onInput={onMaskInput}
                onKeyDown={onMaskKeyDown}
                onKeyPress={onMaskKeyPress}
                onFocus={onMaskFocus}
                onBlur={onMaskBlur}
                onPaste={onMaskPaste}
            />
        </div>
    );
}

Slot Character#

Default placeholder for a mask is underscore that can be customized using slotChar option.

slot-char-demo

'use client';
import { useMask, type UseMaskChangeEvent } from '@primereact/hooks';
import { InputText, type InputTextInstance } from '@primereact/ui/inputtext';
import * as React from 'react';

export default function SlotCharDemo() {
    const [value, setValue] = React.useState('');
    const [target, setTarget] = React.useState<InputTextInstance | null>(null);
    const setInputRef = React.useCallback((instance: InputTextInstance | null) => {
        setTarget(instance);
    }, []);

    const { onMaskInput, onMaskKeyDown, onMaskKeyPress, onMaskFocus, onMaskBlur, onMaskPaste } = useMask({
        mask: '99/99/9999',
        slotChar: 'mm/dd/yyyy',
        onMaskChange: (event: UseMaskChangeEvent) => setValue(event.value ?? ''),
        target
    });

    return (
        <div className="flex justify-center">
            <InputText
                ref={setInputRef}
                placeholder="mm/dd/yyyy"
                value={value}
                onInput={onMaskInput}
                onKeyDown={onMaskKeyDown}
                onKeyPress={onMaskKeyPress}
                onFocus={onMaskFocus}
                onBlur={onMaskBlur}
                onPaste={onMaskPaste}
            />
        </div>
    );
}

Unmask#

By default the bound value contains the formatted mask. Enable unmask option to receive the raw value without the mask characters.

Unmasked value:

unmask-demo

'use client';
import { useMask, type UseMaskChangeEvent } from '@primereact/hooks';
import { InputText, type InputTextInstance } from '@primereact/ui/inputtext';
import * as React from 'react';

export default function UnmaskDemo() {
    const [value, setValue] = React.useState('');
    const [target, setTarget] = React.useState<InputTextInstance | null>(null);
    const setInputRef = React.useCallback((instance: InputTextInstance | null) => {
        setTarget(instance);
    }, []);

    const { onMaskInput, onMaskKeyDown, onMaskKeyPress, onMaskFocus, onMaskBlur, onMaskPaste } = useMask({
        mask: '(999) 999-9999',
        unmask: true,
        onMaskChange: (event: UseMaskChangeEvent) => setValue(event.value ?? ''),
        target
    });

    return (
        <div className="flex flex-col items-center gap-2">
            <InputText
                ref={setInputRef}
                placeholder="(999) 999-9999"
                onInput={onMaskInput}
                onKeyDown={onMaskKeyDown}
                onKeyPress={onMaskKeyPress}
                onFocus={onMaskFocus}
                onBlur={onMaskBlur}
                onPaste={onMaskPaste}
            />
            <span className="text-sm text-muted-color">Unmasked value: {value}</span>
        </div>
    );
}

AutoClear#

When autoClear is set to false, the incomplete value is preserved on blur instead of being cleared.

auto-clear-demo

'use client';
import { useMask, type UseMaskChangeEvent } from '@primereact/hooks';
import { InputText, type InputTextInstance } from '@primereact/ui/inputtext';
import * as React from 'react';

export default function AutoClearDemo() {
    const [value, setValue] = React.useState('');
    const [target, setTarget] = React.useState<InputTextInstance | null>(null);
    const setInputRef = React.useCallback((instance: InputTextInstance | null) => {
        setTarget(instance);
    }, []);

    const { onMaskInput, onMaskKeyDown, onMaskKeyPress, onMaskFocus, onMaskBlur, onMaskPaste } = useMask({
        mask: '(999) 999-9999',
        autoClear: false,
        onMaskChange: (event: UseMaskChangeEvent) => setValue(event.value ?? ''),
        target
    });

    return (
        <div className="flex justify-center">
            <InputText
                ref={setInputRef}
                value={value}
                placeholder="(999) 999-9999"
                onInput={onMaskInput}
                onKeyDown={onMaskKeyDown}
                onKeyPress={onMaskKeyPress}
                onFocus={onMaskFocus}
                onBlur={onMaskBlur}
                onPaste={onMaskPaste}
            />
        </div>
    );
}