# @ionited/mask

> Create your masks easily

Latest version **0.7.0** (published 2025-02-18) · MIT license · 0 weekly downloads

## Install

```sh
npm install @ionited/mask
pnpm add @ionited/mask
yarn add @ionited/mask
bun add @ionited/mask
```

## Health

**Score 35/100 (D)** — status: maintenance-mode.

Positive: has types; esm support; no vulnerabilities.

Warnings: low downloads; pre 1.0.

Negative: stale; low maintenance score.

## Facts

| | |
|---|---|
| Version | 0.7.0 |
| Published | 2025-02-18 |
| First published | 2021-04-08 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Dependencies | 0 |
| Unpacked size | 102.3 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 20 |
| Author | Ion |
| Maintainers | ion-project |
| Keywords | Mask, Core |

## Links

- npm: https://www.npmjs.com/package/@ionited/mask
- Repository: https://github.com/ionited/mask
- Homepage: https://github.com/ionited/mask#readme
- Issues: https://github.com/ionited/mask/issues
- npm.io page: https://npm.io/package/@ionited/mask

## Alternatives

- [lodash.assign](https://npm.io/package/lodash.assign.md) — 2.3M weekly downloads
- [lodash.chunk](https://npm.io/package/lodash.chunk.md) — 1.8M weekly downloads
- [react-native-ios-utilities](https://npm.io/package/react-native-ios-utilities.md) — 138.5K weekly downloads
- [@technically/lodash](https://npm.io/package/@technically/lodash.md) — 50.9K weekly downloads
- [@fluid-topics/ft-icon](https://npm.io/package/@fluid-topics/ft-icon.md) — 20.6K weekly downloads

## Recent versions

- 0.7.0 (latest) — 2025-02-18
- 0.6.4 — 2024-06-26
- 0.6.3 — 2024-06-26
- 0.6.2 — 2024-04-09
- 0.6.1 — 2024-04-09
- 0.6.0 — 2023-10-17
- 0.5.1 — 2023-09-12
- 0.5.0 — 2023-05-26
- 0.4.6 — 2022-09-28
- 0.4.5 — 2022-07-06
- 0.4.4 — 2022-07-06
- 0.4.3 — 2022-07-06
- 0.4.2 — 2021-11-19
- 0.4.1 — 2021-11-18
- 0.4.0 — 2021-10-06
- … 25 more at https://npm.io/package/@ionited/mask/versions

## README

# Mask

> Create your masks easily

Mask comes with three basic implementations MaskDefault, MaskNumber and MaskDate, but you can use MaskCore to do your own masks implementation easily.

## Quick start

Choose your favorite option below:

### Install with NPM

```
npm i @ionited/mask
```

### Get from UNPKG

[https://unpkg.com/@ionited/mask@latest/dist/mask.js](https://unpkg.com/@ionited/mask@latest/dist/mask.js)

---

## Usage

To basic usage you can simply call:

```js
Mask(document.querySelector('#input1'), { mask: '(99) 9999-9999' }); // To use MaskDefault
Mask(document.querySelector('#input2'), { number: true }); // To use MaskNumber
Mask(document.querySelector('#input3'), { date: 'DD/MM/YYYY' }); // To use MaskDate
```

### MaskDefault

A mask that receives a regex or a string with numbers, letters or other symbols

```ts
Mask(el: HTMLElement, { mask: RegExp | string | MaskDefaultOptions });

interface MaskDefaultOptions {
  allowEmpty?: boolean;
  mask: RegExp | string;
}
```

| Symbol   | Pattern          | Description
|:--------:|------------------|-------------
| 9        | `/^[0-9]$/`      | Only numbers
| A        | `/^[A-Za-zÀ-ÿ]$/`| Only letters

Any other symbol is fixed.

### MaskNumber

A mask for monetary and decimal values

```ts
Mask(el: HTMLElement, { number: true | MaskNumberOptions });

interface MaskNumberOptions {
  allowEmpty: boolean;
  allowNegative: boolean;
  decimal: number;
  decimalPoint: string;
  end: boolean;
  prefix: string;
  suffix: string;
  thousandPoint: string;
}
```

### MaskDate

A mask for date and time values

```ts
Mask(el: HTMLElement, { date: string | MaskDateOptions });

interface MaskDateOptions {
  format: string;
  placeholders: { [key: string]: string };
}
```

| Format    | Pattern | Description
|:---------:|---------|-------------
| YYYY      | 0000-∞  | Year
| MM        | 01-12   | Month
| DD        | 01-31   | Day
| hh        | 00-23   | Hour
| mm        | 00-59   | Minutes
| ss        | 00-59   | Seconds

Any other symbol is fixed.

### MaskCore

You can create your own mask logic easily, you only need `register` a mask and use:

```ts
Mask.register(name: string, mask: any): void;
```

The recommended way to do a new mask is writing a class that extends `MaskOptions`

```ts
interface MaskOptions {
  instance: MaskCore;
  init?(data: MaskData): void;
  input?(data: MaskData): void;
  format(data: MaskData): void;
  focus?(data: MaskData): void;
  blur?(data: MaskData): void;
  mouseover?(data: MaskData): void;
  mouseout?(data: MaskData): void;
}

interface MaskData {
  cursorPosition: number;
  delete: boolean;
  focus: boolean;
  input: string;
  output: string;
  outputRaw: any;
}
```

MyMask example (only accept numbers):

```ts
import { MaskData, MaskCore, MaskOptions } from '@ionited/mask/core';

export class MyMask implements MaskOptions {
  instance: MaskCore;

  constructor(el: HTMLInputElement) {
    this.instance = new MaskCore(el, this);
  }

  init(data: MaskData) {
    this.format(data);
  }

  format(data: MaskData) {
    data.output = data.input.replace(/[^0-9]/g, ''); 
  }
}
```

Register and use:

```ts
Mask.register('myMask', MyMask); // Register

Mask(document.querySelector('#myMask'), { myMask: true }); // Enjoy your own mask!
```

## License

Copyright (c) 2021 Ion. Licensed under [MIT License](LICENSE).

[https://ionited.io](https://ionited.io)

---
_Source: https://npm.io/package/@ionited/mask · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._