ngx-mask

ngx-mask

Version 22.2.1
Published 5 days ago
648 kB
1 dependency
MIT license

Install

npm i ngx-mask

yarn add ngx-mask

pnpm add ngx-mask

Overview

Input masking for modern Angular — Reactive, template-driven and Signal Forms, zoneless and SSR ready. Dates, numbers, separators, custom patterns.

Index

Variables

variable INITIAL_CONFIG

const INITIAL_CONFIG: InjectionToken<NgxMaskConfig>;

variable initialConfig

const initialConfig: NgxMaskConfig;

variable NEW_CONFIG

const NEW_CONFIG: InjectionToken<NgxMaskConfig>;

variable NGX_MASK_CONFIG

const NGX_MASK_CONFIG: InjectionToken<NgxMaskConfig>;

variable timeMasks

const timeMasks: string[];

variable withoutValidation

const withoutValidation: string[];

Functions

function provideEnvironmentNgxMask

provideEnvironmentNgxMask: (
    configValue?: NgxMaskOptions | (() => NgxMaskOptions)
) => EnvironmentProviders;

function provideNgxMask

provideNgxMask: (
    configValue?: NgxMaskOptions | (() => NgxMaskOptions)
) => Provider[];

function resolveMaskAlias

resolveMaskAlias: (
    maskExpression: string | null | undefined,
    maskAliases: Record<string, string> | undefined
) => string;

Resolves a user-defined mask alias to its mask expression. Returns the input expression unchanged when no alias matches or when the alias key shadows a built-in token (in which case a console warning is emitted once per key and the built-in wins).

Classes

class NgxMaskDirective

class NgxMaskDirective
    implements
        ControlValueAccessor,
        OnChanges,
        Validator,
        FormValueControl<string | number | null | undefined> {}

constructor

constructor();

property allowNegativeNumbers

allowNegativeNumbers: _angular_core.InputSignal<boolean>;

property apm

apm: _angular_core.InputSignal<boolean>;

property clearIfNotMatch

clearIfNotMatch: _angular_core.InputSignal<boolean>;

property decimalMarker

decimalMarker: _angular_core.InputSignal<any>;

property defaultValueOnBlur

defaultValueOnBlur: _angular_core.InputSignal<string>;

property disabled

disabled: _angular_core.InputSignalWithTransform<boolean, unknown>;

property dropSpecialCharacters

dropSpecialCharacters: _angular_core.InputSignal<
    boolean | string[] | readonly string[]
>;

property hiddenInput

hiddenInput: _angular_core.InputSignal<boolean>;

property inputTransformFn

inputTransformFn: _angular_core.InputSignal<any>;

property instantPrefix

instantPrefix: _angular_core.InputSignal<boolean>;

property keepCharacterPositions

keepCharacterPositions: _angular_core.InputSignal<boolean>;

property leadZero

leadZero: _angular_core.InputSignal<boolean>;

property leadZeroDateTime

leadZeroDateTime: _angular_core.InputSignal<boolean>;

property mask

mask: _angular_core.InputSignal<string>;

property maskFilled

maskFilled: _angular_core.OutputEmitterRef<void>;

property onChange

onChange: (_: unknown) => void;

property onTouch

onTouch: () => void;

property outputTransformFn

outputTransformFn: _angular_core.InputSignal<any>;

property ɵdir

static ɵdir: _angular_core.ɵɵDirectiveDeclaration<
    NgxMaskDirective,
    'input[mask], textarea[mask]',
    ['mask', 'ngxMask'],
    {
        mask: { alias: 'mask'; required: false; isSignal: true };
        specialCharacters: {
            alias: 'specialCharacters';
            required: false;
            isSignal: true;
        };
        patterns: { alias: 'patterns'; required: false; isSignal: true };
        prefix: { alias: 'prefix'; required: false; isSignal: true };
        suffix: { alias: 'suffix'; required: false; isSignal: true };
        thousandSeparator: {
            alias: 'thousandSeparator';
            required: false;
            isSignal: true;
        };
        decimalMarker: {
            alias: 'decimalMarker';
            required: false;
            isSignal: true;
        };
        dropSpecialCharacters: {
            alias: 'dropSpecialCharacters';
            required: false;
            isSignal: true;
        };
        hiddenInput: { alias: 'hiddenInput'; required: false; isSignal: true };
        showMaskTyped: {
            alias: 'showMaskTyped';
            required: false;
            isSignal: true;
        };
        placeHolderCharacter: {
            alias: 'placeHolderCharacter';
            required: false;
            isSignal: true;
        };
        shownMaskExpression: {
            alias: 'shownMaskExpression';
            required: false;
            isSignal: true;
        };
        clearIfNotMatch: {
            alias: 'clearIfNotMatch';
            required: false;
            isSignal: true;
        };
        validation: { alias: 'validation'; required: false; isSignal: true };
        separatorLimit: {
            alias: 'separatorLimit';
            required: false;
            isSignal: true;
        };
        typeFromDecimals: {
            alias: 'typeFromDecimals';
            required: false;
            isSignal: true;
        };
        allowNegativeNumbers: {
            alias: 'allowNegativeNumbers';
            required: false;
            isSignal: true;
        };
        leadZeroDateTime: {
            alias: 'leadZeroDateTime';
            required: false;
            isSignal: true;
        };
        leadZero: { alias: 'leadZero'; required: false; isSignal: true };
        triggerOnMaskChange: {
            alias: 'triggerOnMaskChange';
            required: false;
            isSignal: true;
        };
        apm: { alias: 'apm'; required: false; isSignal: true };
        inputTransformFn: {
            alias: 'inputTransformFn';
            required: false;
            isSignal: true;
        };
        outputTransformFn: {
            alias: 'outputTransformFn';
            required: false;
            isSignal: true;
        };
        keepCharacterPositions: {
            alias: 'keepCharacterPositions';
            required: false;
            isSignal: true;
        };
        instantPrefix: {
            alias: 'instantPrefix';
            required: false;
            isSignal: true;
        };
        defaultValueOnBlur: {
            alias: 'defaultValueOnBlur';
            required: false;
            isSignal: true;
        };
        value: { alias: 'value'; required: false; isSignal: true };
        disabled: { alias: 'disabled'; required: false; isSignal: true };
        touched: { alias: 'touched'; required: false; isSignal: true };
    },
    { value: 'valueChange'; touched: 'touchedChange'; maskFilled: 'maskFilled' },
    never,
    never,
    true,
    never
>;

property ɵfac

static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxMaskDirective, never>;

property patterns

patterns: _angular_core.InputSignal<
    Record<string, { pattern: RegExp; optional?: boolean; symbol?: string }>
>;

property placeHolderCharacter

placeHolderCharacter: _angular_core.InputSignal<string>;

property prefix

prefix: _angular_core.InputSignal<string>;

property separatorLimit

separatorLimit: _angular_core.InputSignal<string>;

property showMaskTyped

showMaskTyped: _angular_core.InputSignal<boolean>;

property shownMaskExpression

shownMaskExpression: _angular_core.InputSignal<string>;

property specialCharacters

specialCharacters: _angular_core.InputSignal<string[] | readonly string[]>;

property suffix

suffix: _angular_core.InputSignal<string>;

property thousandSeparator

thousandSeparator: _angular_core.InputSignal<string>;

property touched

touched: _angular_core.ModelSignal<boolean>;

property triggerOnMaskChange

triggerOnMaskChange: _angular_core.InputSignal<boolean>;

property typeFromDecimals

typeFromDecimals: _angular_core.InputSignal<boolean>;

property validation

validation: _angular_core.InputSignal<boolean>;

property value

value: _angular_core.ModelSignal<string | number>;

Signal Forms FormValueControl surface. At runtime FormField never drives this model when the directive is bound (it prefers the NG_VALUE_ACCESSOR provided above, see _isCvaMode), but the template type-checker treats any directive owning a value model as the field's custom control and checks the bound field's value type against it (#1640). The model therefore accepts exactly what writeValue() accepts — `string | number | null | undefined — so numeric and nullable fields (signal({ amount: 0 })`, signal<number | null>(null), signal<string | null>(null)) compile under strictTemplates. Values pushed back into the model are always the unmasked string (see _propagateToValueModel), i.e. value() / valueChange are declared wider than what is emitted.

method checkSelectionOnDeletion

checkSelectionOnDeletion: (el: HTMLInputElement) => void;

method focus

focus: () => void;

Focus the input element. Required by FormValueControl interface for Signal Forms.

method ngOnChanges

ngOnChanges: (changes: SimpleChanges) => void;

method onBlur

onBlur: (e: Event) => void;

method onClick

onClick: (e: Event) => void;

method onCompositionEnd

onCompositionEnd: (e: Event) => void;

method onCompositionStart

onCompositionStart: () => void;

method onFocus

onFocus: () => void;

method onInput

onInput: (e: Event) => void;

method onKeyDown

onKeyDown: (event: Event) => void;

method onModelChange

onModelChange: (value: unknown) => void;

method onPaste

onPaste: () => void;

method registerOnChange

registerOnChange: (fn: typeof this.onChange) => void;

method registerOnTouched

registerOnTouched: (fn: typeof this.onTouch) => void;

method setDisabledState

setDisabledState: (isDisabled: boolean) => void;

It disables the input element.
Mirrors _writeElementValueSync (#1305): the service's formElementProperty setter defers ALL DOM writes via queueMicrotask to dodge ExpressionChangedAfterItHasBeenChecked and keep FIFO ordering with config-driven re-renders. For disabled specifically, that deferral leaves nativeElement.disabled stale for at least one microtask after Angular Forms' setUpControl calls this method synchronously during init — long enough for a consumer reading the DOM property in the same synchronous phase (or another deferred write racing in FIFO order) to observe the wrong value, e.g. an initially-disabled FormControl whose native input briefly (or, depending on interleaving, persistently) reports disabled === false (#1633). Writing synchronously here closes that gap; the deferred write below still runs afterwards and re-applies the same final value, preserving the existing ordering guarantees other call sites rely on.

method validate

validate: ({ value }: FormControl) => ValidationErrors | null;

method writeValue

writeValue: (controlValue: unknown) => void;

It writes the value in the input

class NgxMaskPipe

class NgxMaskPipe implements PipeTransform {}

property ɵfac

static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxMaskPipe, never>;

property ɵpipe

static ɵpipe: _angular_core.ɵɵPipeDeclaration<NgxMaskPipe, 'mask', true>;

method transform

transform: (
    value: string | number,
    mask: string,
    { patterns, maskAliases, ...config }?: Partial<NgxMaskConfig>
) => string;

class NgxMaskService

class NgxMaskService extends NgxMaskApplierService {}

property currentValue

currentValue: string;

property isInitialized

isInitialized: boolean;

property isNumberValue

isNumberValue: boolean;

property keepCharacterPositionsHandled

keepCharacterPositionsHandled: boolean;

Set by the directive's keepCharacterPositions handling for the current edit: true — the directive fully resolved the resulting display value into actualValue, so applyMask must short-circuit and render actualValue as-is; false — the edit must flow through regular masking (no short-circuit); null — the directive was not involved in this applyMask call (legacy behavior). Consumed and reset by applyMask. This lets keepCharacterPositions work without showMaskTyped (#1545, #1543).

property maskChanged

maskChanged: boolean;

property maskExpressionArray

maskExpressionArray: string[];

property maskIsShown

maskIsShown: string;

property onChange

onChange: (_: unknown) => void;

property ɵfac

static ɵfac: _angular_core.ɵɵFactoryDeclaration<NgxMaskService, never>;

property ɵprov

static ɵprov: _angular_core.ɵɵInjectableDeclaration<any>;

property previousValue

previousValue: string;

property selEnd

selEnd: number;

property selStart

selStart: number;

method applyMask

applyMask: (
    inputValue: string,
    maskExpression: string,
    position?: number,
    justPasted?: boolean,
    backspaced?: boolean,
    cb?: (actualShift: number, backspaceShift: boolean) => void
) => string;

Applies the mask to the input value.
Parameter inputValue
The input value to be masked.
Parameter maskExpression
The mask expression to apply.
Parameter position
The position in the input value.
Parameter justPasted
Whether the value was just pasted.
Parameter backspaced
Whether the value was backspaced.
Parameter cb
Callback function.
Returns
The masked value.

method applyValueChanges

applyValueChanges: (
    position: number,
    justPasted: boolean,
    backspaced: boolean,
    cb?: (actualShift: number, backspaceShift: boolean) => void
) => void;

method checkDropSpecialCharAmount

checkDropSpecialCharAmount: (mask: string) => number;

method clearIfNotMatchFn

clearIfNotMatchFn: () => void;

method currentLocaleDecimalMarker

currentLocaleDecimalMarker: () => string;

Decimal marker of the value being normalized in writeValue/pipe flows.
#1573: this used to return the RUNTIME default locale's decimal marker ((1.1).toLocaleString().substring(1, 2)), which made mask behavior depend on the OS/browser regional format: under a comma-decimal locale (e.g. Edge + Austrian regional settings) a preformatted value like '10,000' (thousandSeparator ',') had its ',' replaced by the configured '.' decimalMarker, corrupting the value 1000x. JS number stringification (String(n)) always uses '.', and string values are expected to use the configured markers — the runtime locale is never the right source, so this is always '.'.

method formControlResult

formControlResult: (inputValue: string) => void;

Propogates the input value back to the Angular model by triggering the onChange function. It won't do this if writingValue is true. If that is true it means we are currently in the writeValue function, which is supposed to only update the actual DOM element based on the Angular model value. It should be a one way process, i.e. writeValue should not be modifying the Angular model value too. Therefore, we don't trigger onChange in this scenario.
Parameter inputValue
the current form input value

method getActualValue

getActualValue: (res: string) => string;

method hideInput

hideInput: (inputValue: string, maskExpression: string) => string;

method numberToString

numberToString: (value: number | string) => string;

Convert number value to string 3.1415 -> '3.1415' 1e-7 -> '0.0000001'

method removeMask

removeMask: (inputValue: string) => string;

method shiftTypedSymbols

shiftTypedSymbols: (inputValue: string) => string;

method showMaskInInput

showMaskInInput: (inputVal?: string) => string;

Type Aliases

type DecimalMarkerChar

type DecimalMarkerChar = '.' | ',';

Single decimal marker character accepted when decimalMarker is given as an array.

type InputTransformFn

type InputTransformFn = (value: unknown) => string | number;

type NgxMaskConfig

type NgxMaskConfig = {
    suffix: string;
    prefix: string;
    thousandSeparator: string;
    decimalMarker: DecimalMarkerChar | [DecimalMarkerChar, DecimalMarkerChar];
    clearIfNotMatch: boolean;
    showMaskTyped: boolean;
    placeHolderCharacter: string;
    shownMaskExpression: string;
    specialCharacters: string[] | readonly string[];
    dropSpecialCharacters: boolean | string[] | readonly string[];
    hiddenInput: boolean;
    validation: boolean;
    instantPrefix: boolean;
    separatorLimit: string;
    apm: boolean;
    allowNegativeNumbers: boolean;
    leadZeroDateTime: boolean;
    leadZero: boolean;
    /**
     * Opt-in "banking" typing mode for separator masks with a fixed precision
     * (`separator.N`, N > 0): typed digits fill the value from the decimal end,
     * ATM/calculator style (5 -> 0.05 -> 0.57 -> 5.73); backspace shifts digits
     * back to the right. Pasted and model-written values keep the regular
     * separator formatting. Config-only option (provideNgxMask / pipe config) —
     * it has no directive input.
     */
    typeFromDecimals: boolean;
    triggerOnMaskChange: boolean;
    keepCharacterPositions: boolean;
    inputTransformFn: InputTransformFn;
    outputTransformFn: OutputTransformFn;
    maskFilled: EventEmitter<void>;
    /**
     * User-defined named mask aliases resolved at the DI-config level (static per injector).
     * When the `mask` input (or pipe mask argument) exactly matches an alias key, the aliased
     * expression is substituted before any other mask processing (including `||` multi-masks).
     * Alias keys must not shadow built-in tokens (IP, CPF_CNPJ, CPF_CNPJ_ALPHA, ...) — such
     * aliases are ignored with a one-time console warning.
     */
    maskAliases: Record<string, string>;
    /**
     * When set, this raw value is written through the regular mask pipeline on blur
     * whenever the control's unmasked value is empty (covers '', a bare prefix/suffix and
     * the showMaskTyped skeleton): the display shows the masked default and the model
     * receives the usual output (dropSpecialCharacters/outputTransformFn applied). The
     * write keeps the control's pristine state. `null` (default) keeps current behavior.
     */
    defaultValueOnBlur: string | null;
    patterns: Record<
        string,
        {
            pattern: RegExp;
            optional?: boolean;
            symbol?: string;
        }
    >;
};

type NgxMaskOptions

type NgxMaskOptions = Partial<NgxMaskConfig>;

type OutputTransformFn

type OutputTransformFn = (value: string | number | undefined | null) => unknown;

Package Files (1)

types/ngx-mask.d.ts

Dependencies (1)

tslib

Dev Dependencies (0)

No dev dependencies.

Peer Dependencies (3)

Badge

To add a badge like this oneto your package's README, use the codes available below.

You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/ngx-mask.

Markdown

[![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/ngx-mask)

HTML

<a href="https://www.jsdocs.io/package/ngx-mask"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>

Updated 5 days ago.
Package analyzed in 3061 ms.
Missing or incorrect documentation? Open an issue for this package.