@altricade/react-mask-field/dist/index.d.ts

A modern, flexible and accessible input mask component for React

import React$1, { InputHTMLAttributes, ChangeEvent, KeyboardEvent } from 'react';

type FormatChars = {
    [key: string]: string;
};
type BeforeMaskedValueChangeFunction = (newState: {
    value: string;
    selection: {
        start: number | null;
        end: number | null;
    };
}, oldState: {
    value: string;
    selection: {
        start: number | null;
        end: number | null;
    };
}, userInput: string | null, maskOptions: {
    mask: string | Array<string | RegExp>;
    maskChar: string;
    formatChars?: FormatChars;
}) => {
    value: string;
    selection: {
        start: number | null;
        end: number | null;
    };
};
interface MaskFieldProps extends Omit<InputHTMLAttributes<HTMLInputElement>, 'onChange'> {
    /**
     * Mask pattern. Default format characters are:
     * - 9: 0-9
     * - a: A-Z, a-z
     * - *: A-Z, a-z, 0-9
     * Any character can be escaped with backslash, e.g. \9
     */
    mask: string;
    /**
     * Character to cover unfilled parts of the mask. Default character is "_".
     * If set to null or empty string, unfilled parts will be empty.
     */
    maskChar?: string;
    /**
     * Defines format characters with a key-value map where keys are characters
     * and values are their corresponding RegExp strings.
     * Default: { '9': '[0-9]', 'a': '[A-Za-z]', '*': '[A-Za-z0-9]' }
     */
    formatChars?: FormatChars;
    /**
     * Show mask when input is empty and has no focus.
     */
    alwaysShowMask?: boolean;
    /**
     * Function that is called before masked value is changed.
     * Can be used to modify the masked value or selection.
     */
    beforeMaskedValueChange?: BeforeMaskedValueChangeFunction;
    /**
     * Called when input value changes.
     */
    onChange?: (event: React.ChangeEvent<HTMLInputElement>) => void;
    /**
     * Character used for placeholders in mask pattern.
     */
    placeholderChar?: string;
    /**
     * Show a placeholder with a different color for unfilled positions.
     */
    showPlaceholder?: boolean;
    /**
     * Color for the placeholder characters.
     */
    placeholderColor?: string;
    /**
     * If true, the input will be marked as having an error.
     */
    error?: boolean;
    /**
     * Helper text to display below the input.
     */
    helperText?: React.ReactNode;
    /**
     * Color for the error state border and text.
     * Default is '#d32f2f' (red).
     */
    errorColor?: string;
    /**
     * Custom styles for the helper text container.
     */
    helperTextStyle?: React.CSSProperties;
}

declare const MaskField: React$1.ForwardRefExoticComponent<MaskFieldProps & React$1.RefAttributes<HTMLInputElement>>;

interface UseMaskProps {
    mask: string;
    value: string;
    maskChar?: string;
    formatChars?: FormatChars;
    beforeMaskedValueChange?: BeforeMaskedValueChangeFunction;
    showPlaceholder?: boolean;
    placeholderChar?: string;
}
declare function useMask({ mask, value, maskChar, formatChars, beforeMaskedValueChange, showPlaceholder, placeholderChar, }: UseMaskProps): {
    maskedValue: string;
    rawValue: string;
    handleChange: (e: ChangeEvent<HTMLInputElement>) => void;
    handleKeyDown: (e: KeyboardEvent<HTMLInputElement>) => void;
    setInputValue: (input: HTMLInputElement, value: string) => void;
    setSelection: (input: HTMLInputElement, selection: {
        start: number;
        end: number;
    }) => void;
};

interface PhoneInputProps extends Omit<MaskFieldProps, 'mask'> {
    /**
     * Country code format - defaults to US/Canada format
     */
    countryCode?: 'US' | 'CA' | 'UK' | 'AU' | 'IN' | 'RU' | 'custom';
    /**
     * Custom mask to use when countryCode is 'custom'
     */
    customMask?: string;
}
declare const PhoneInput: React$1.ForwardRefExoticComponent<PhoneInputProps & React$1.RefAttributes<HTMLInputElement>>;

interface DateInputProps extends Omit<MaskFieldProps, 'mask'> {
    /**
     * Date format to use - defaults to 'MM/DD/YYYY'
     */
    format?: 'MM/DD/YYYY' | 'DD/MM/YYYY' | 'YYYY-MM-DD' | 'MM-DD-YYYY' | 'DD-MM-YYYY';
    /**
     * Separator character to use in the date format
     */
    separator?: '/' | '-' | '.';
    /**
     * Enable validation of the date as a valid calendar date
     */
    enableDateValidation?: boolean;
}
declare const DateInput: React$1.ForwardRefExoticComponent<DateInputProps & React$1.RefAttributes<HTMLInputElement>>;

interface CreditCardInputProps extends Omit<MaskFieldProps, 'mask'> {
    /**
     * Callback when card type is detected
     */
    onCardTypeChange?: (cardType: CardType | null) => void;
    /**
     * Force a specific card type mask
     */
    cardType?: CardType;
    /**
     * Enable auto-detection of card type from number
     */
    detectCardType?: boolean;
}
type CardType = 'visa' | 'mastercard' | 'amex' | 'discover' | 'diners' | 'jcb' | 'unionpay' | 'other';
declare const CreditCardInput: React$1.ForwardRefExoticComponent<CreditCardInputProps & React$1.RefAttributes<HTMLInputElement>>;

interface TimeInputProps extends Omit<MaskFieldProps, 'mask'> {
    /**
     * Time format to use
     */
    format?: '12h' | '24h';
    /**
     * Whether to show seconds
     */
    showSeconds?: boolean;
    /**
     * Separator character to use between hours, minutes, and seconds
     */
    separator?: ':' | '.';
    /**
     * Enable validation of time values (e.g., hours 0-23, minutes 0-59)
     */
    enableTimeValidation?: boolean;
}
declare const TimeInput: React$1.ForwardRefExoticComponent<TimeInputProps & React$1.RefAttributes<HTMLInputElement>>;

export { type BeforeMaskedValueChangeFunction, type CardType, CreditCardInput, DateInput, type FormatChars, MaskField, type MaskFieldProps, PhoneInput, TimeInput, useMask };