useMask

useMask 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/inputtext';
import * as React from 'react';

export default function BasicDemo() {
    const [value, setValue] = React.useState('');
    const ref = React.useRef<InputTextInstance>(null);
    const [target, setTarget] = React.useState<HTMLInputElement | null>(null);

    React.useEffect(() => {
        if (ref.current?.elementRef?.current) {
            setTarget(ref.current.elementRef.current as HTMLInputElement);
        }
    }, []);

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

    return (
        <div className="flex justify-center">
            <InputText
                ref={ref}
                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

format-patterns-demo

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

export default function FormatPatternsDemo() {
    const [value1, setValue1] = React.useState('');
    const [value2, setValue2] = React.useState('');
    const [value3, setValue3] = React.useState('');
    const input1 = React.useRef<InputTextInstance>(null);
    const input2 = React.useRef<InputTextInstance>(null);
    const input3 = React.useRef<InputTextInstance>(null);
    const [target1, setTarget1] = React.useState<HTMLInputElement | null>(null);
    const [target2, setTarget2] = React.useState<HTMLInputElement | null>(null);
    const [target3, setTarget3] = React.useState<HTMLInputElement | null>(null);

    React.useEffect(() => {
        if (input1.current?.elementRef?.current) {
            setTarget1(input1.current.elementRef.current as HTMLInputElement);
        }

        if (input2.current?.elementRef?.current) {
            setTarget2(input2.current.elementRef.current as HTMLInputElement);
        }

        if (input3.current?.elementRef?.current) {
            setTarget3(input3.current.elementRef.current as HTMLInputElement);
        }
    }, []);

    // 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 as HTMLInputElement
    });

    // 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 as HTMLInputElement
    });

    // 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 as HTMLInputElement
    });

    return (
        <div className="flex flex-wrap gap-4">
            <div className="flex-auto">
                <Label htmlFor="ssn" className="font-bold block mb-2">
                    SSN
                </Label>
                <InputText
                    ref={input1}
                    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="font-bold block mb-2">
                    Phone
                </Label>
                <InputText
                    ref={input2}
                    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="font-bold block mb-2">
                    Serial
                </Label>
                <InputText
                    ref={input3}
                    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/inputtext';
import * as React from 'react';

export default function OptionalDemo() {
    const [value, setValue] = React.useState('');
    const ref = React.useRef<InputTextInstance>(null);
    const [target, setTarget] = React.useState<HTMLInputElement | null>(null);

    React.useEffect(() => {
        if (ref.current?.elementRef?.current) {
            setTarget(ref.current.elementRef.current as HTMLInputElement);
        }
    }, []);

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

    return (
        <div className="flex justify-center">
            <InputText
                ref={ref}
                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 * as React from 'react';

export default function SlotCharDemo() {
    const [value, setValue] = React.useState('');
    const ref = React.useRef<HTMLInputElement>(null);
    const [target, setTarget] = React.useState<HTMLInputElement | null>(null);

    React.useEffect(() => {
        if (ref.current) {
            setTarget(ref.current as HTMLInputElement);
        }
    }, []);

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

    return (
        <div className="flex justify-center">
            <input
                type="text"
                ref={ref}
                placeholder="mm/dd/yyyy"
                value={value}
                onInput={onMaskInput}
                onKeyDown={onMaskKeyDown}
                onKeyPress={onMaskKeyPress}
                onFocus={onMaskFocus}
                onBlur={onMaskBlur}
                onPaste={onMaskPaste}
                className="border border-gray-300 rounded-md px-3 py-1"
            />
        </div>
    );
}