npm package: @gruzf/mask-input
Description: React masked input component
Author: Timur Lagutin
Latest version: 2.1.7

# GRUZF MaskInput

[![Version](https://img.shields.io/badge/dynamic/json?color=green&label=numen&prefix=v&query=%24%5B%27dist-tags%27%5D.latest&url=https%3A%2F%2Fregistry.npmjs.org%2F%40gruzf%2Fnumen)](https://npmjs.org/package/@gruzf/numen)
[![Company](https://img.shields.io/badge/company-@gruzf-blue)](https://www.npmjs.com/org/gruzf)

Input masking component for React. Made with attention to UX.

> GRUZF MaskInput is written in `TypeScript`.

# Table of Contents

- [Install](#install)
- [Usage](#usage)
- [Properties](#properties)
  - [mask](#mask)
  - [maskPlaceholder](#maskplaceholder)
  - [alwaysShowMask](#alwaysshowmask)
  - [beforeMaskedStateChange](#beforemaskedstatechange)
  - [unmask](#unmask)
  - [fullFilled](#fullfilled)
  - [onlyDigitAndLetter](#onlydigitandletter)
- [maskedString](#maskedstring)
- [Known Issues](#known-issues)

# Install

```bash
npm install @gruzf/mask-input
```

or

```bash
yarn add @gruzf/mask-input
```

:warning: @gruzf/mask-input requires **React 16.8.0 or later.**

# Usage

```jsx
import MaskInput from "@gruzf/mask-input";
import React from "react";

function DateInput(props) {
  return (
    <MaskInput
      mask="99/99/9999"
      onChange={props.onChange}
      value={props.value}
    />
  );
}
```

# Properties

|                           Name                            |               Type                |        Default         | Description                                                                                  |
| :-------------------------------------------------------: | :-------------------------------: | :--------------------: | :------------------------------------------------------------------------------------------- |
|                    **[`mask`](#mask)**                    | `{String\|Array<String, RegExp>}` | `"+7 (999) 999-99-99"` | Mask format                                                                                  |
|         **[`maskPlaceholder`](#maskplaceholder)**         |         `{String\|null}`          |         `null`         | Placeholder to cover unfilled parts of the mask                                              |
|          **[`alwaysShowMask`](#alwaysshowmask)**          |            `{Boolean}`            |        `false`         | Whether mask prefix and placeholder should be displayed when input is empty and has no focus |
| **[`beforeMaskedStateChange`](#beforemaskedstatechange)** |           `{Function}`            |                        | Function to modify value and selection before applying mask                                  |
|                  **[`unmask`](#unmask)**                  |            `{Boolean}`            |        `false`         | Value format                                                                                 |
|              **[`fullFilled`](#fullfilled)**              |            `{Boolean}`            |     `type==="tel"`     | Value will be empty string until the user completely fills in the masked field.              |
|      **[`onlyDigitAndLetter`](#onlydigitandletter)**      |            `{Boolean}`            |     `type==="tel"`     | Value will contain only letters and digits                                                   |
|                **[`children`](#children)**                |         `{ReactElement}`          |                        | Custom render function for integration with other input components                           |

And other **InputHTMLAttributes** that are passed to the `<input/>` or to the passed `children` wich contains `<input/>`.

### `mask`

Mask format. Can be either a string or array of characters and regular expressions.
**Default mask**: `"+7 (999) 999-99-99"`.
_If the `mask` was not passed, the default input `type` attribute will switch to `'tel'`_

```jsx
<MaskInput mask="99/99/99" />
```

The same mask by regex array:

```jsx
<MaskInput mask={[/\d/, /\d/, "\\", /\d/, /\d/, "\\", /\d/, /\d/]} />
```

<br />
Simple masks can be defined as strings. The following characters will define mask format:

| Character | Allowed input |
| :-------: | :-----------: |
|     9     |      0-9      |
|     a     |   a-z, A-Z    |
|    \*     | 0-9, a-z, A-Z |

Any format character can be escaped with a backslash.<br /><br />

More complex masks can be defined as an array of regular expressions and constant characters.

```jsx
// Canadian postal code mask
const firstLetter = /(?!.*[DFIOQU])[A-VXY]/i;
const letter = /(?!.*[DFIOQU])[A-Z]/i;
const digit = /[0-9]/;
const mask = [firstLetter, digit, letter, " ", digit, letter, digit];

return <MaskInput mask={mask} />;
```

### `maskPlaceholder`

**Default:** `null`

Character or string to cover unfilled parts of the mask.

```jsx
// Will be rendered as 12/--/--
<MaskInput mask="99/99/99" maskPlaceholder="-" value="12" />

// Will be rendered as 12/mm/yy
<MaskInput mask="99/99/99" maskPlaceholder="dd/mm/yy" value="12" />

// Will be rendered as 12/
<MaskInput mask="99/99/99" maskPlaceholder={null} value="12" />
```

### `alwaysShowMask`

**Default:** `false`

If enabled, mask prefix and placeholder will be displayed even when input is empty and has no focus.

### `beforeMaskedStateChange`

In case you need to customize masking behavior, you can provide `beforeMaskedStateChange` function to change masked value and cursor position before it's applied to the input.

It receieves an object with `previousState`, `currentState` and `nextState` properties. Each state is an object with `value` and `selection` properites where `value` is a string and selection is an object containing `start` and `end` positions of the selection.

1. **previousState:** Input state before change. Only defined on `change` event.
2. **currentState:** Current raw input state. Not defined during component render.
3. **nextState:** Input state with applied mask. Contains `value` and `selection` fields.

Selection positions will be `null` if input isn't focused and during rendering.

`beforeMaskedStateChange` must return a new state with `value` and `selection`.

```jsx
// Trim trailing slashes
function beforeMaskedStateChange({ nextState }) {
  let { value } = nextState;
  if (value.endsWith("/")) {
    value = value.slice(0, -1);
  }

  return {
    ...nextState,
    value
  };
}

return <MaskInput mask="99/99/99" beforeMaskedStateChange={beforeMaskedStateChange} />;
```

```tsx
import MaskInput, { BeforeMaskedStateChangeStates } from "@gruzf/mask-input";

let mask = [/[0-2]/, /\d/, ":", /[0-5]/, /\d/];

// Timer input like "12:59"
const beforeMaskedStateChange = (states: BeforeMaskedStateChangeStates) => {
  let { value, selection } = states.nextState;

  if (value.startsWith("2")) {
    mask[1] = /[0-3]/;
  } // To block 24, 25, etc.
  else {
    mask[1] = /\d/;
  } // To allow 05, 12, etc.
  return { value, selection };
};

return <MaskInput mask={mask} beforeMaskedStateChange={beforeMaskedStateChange} />;
```

Please note that `beforeMaskedStateChange` executes more often than `onChange` and must be pure.

### `unmask`

**Default:** `false`

If enabled, displayed value will be with mask, but input value will be without mask.

- false:

  ```jsx
    // default mask: "+7 (999) 999-99-99"
    // passed value: "+7 (123) 456-78-90"
    // displayed value: "+7 (123) 456-78-90"
    // input value: "+7 (123) 456-78-90"
    return <MaskInput value="+7 (123) 456-78-90"/>
  ```

- true:

  ```jsx
    // default mask: "+7 (999) 999-99-99"
    // passed value: "+7 (123) 456-78-90"
    // displayed value: "+7 (123) 456-78-90"
    // input value: "1234567890"
    return <MaskInput value="+7 (123) 456-78-90" unmask/>
  ```

### `fullFilled`

**Default:** prop `type` === "tel"

If enabled, input value will be empty string until the user completely fills in the masked field.

- false:

  ```jsx
    // type !== "tel" => fullFilled={false}
    // displayed value: "1234 567"
    // input value: "1234 567"
    return <MaskInput  mask={"9999 9999 9999 9999"} value="1234567" />
  ```

- true:

  - not filled
    ```jsx
      // displayed value: "1234 567"
      // input value: ""
      return <MaskInput  mask={"9999 9999 9999 9999"} value="1234567" fullFilled/>
    ```
  - full filled
    ```jsx
      // displayed value: "1234 5678 9012 3456"
      // input value: "1234 5678 9012 3456"
      return <MaskInput  mask={"9999 9999 9999 9999"} value="1234567890123456" fullFilled/>
    ```

### `onlyDigitAndLetter`

**Default:** prop `type` === "tel"

If enabled, input value will contain only digits and letters.

```jsx
  // default mask: "+7 (999) 999-99-99"
  // passed value: "+7 (123) 456-78-90"
  // displayed value: "+7 (123) 456-78-90"
  // onlyDigitAndLetter = true because prop `type` === "tel"
  // input value: "71234567890"
    return <MaskInput value="+7 (123) 456-78-90"/>
```

```jsx
  // passed value: "--74_vg_R"
  // displayed value: "--74_vg_R"
  // input value: ""74vgR""
  return <MaskInput mask="--99_aa_*" value="--74_vg_R" onlyDigitAndLetter/>
```

### `children`

To use another component instead of regular `<input />` provide it as children. The following properties, if used, should always be defined on the `MaskInput` component itself: `onChange`, `onMouseDown`, `onFocus`, `onBlur`, `value`, `disabled`, `readOnly`.

```jsx
import MaskInput from "@gruzf/mask-input";
import { TextField } from "@mui/material";
import React from "react";

// Will work fine
function Input(props) {
  return (
    <MaskInput
      mask="99/99/9999"
      value={props.value}
      onChange={props.onChange}
      type="tel"
    >
      <TextField size="small" variant="filled" />
    </MaskInput>
  );
}

// Will throw an error because MaskInput's and children's onChange props aren't the same
function InvalidInput(props) {
  return (
    <MaskInput mask="99/99/9999" value={props.value}>
      <TextField type="tel" disableUnderline onChange={props.onChange} />
    </MaskInput>
  );
}
```

# maskedString

You can use function `maskedString` to apply your mask on a string.

`maskedString(value, mask, type)`

- `value` - string
- `mask` - mask to apply on your value
- `type` - type of your value: `"text"` or `"tel"`. Default: `"tel"`

```js
import { maskedString } from "@gruzf/mask-input";

maskedString("1234567890", "+7 (999) 999-99-99"); // +7 (123) 456-78-90
```

# Known Issues

### Autofill

Browser's autofill requires either empty value in input or value which exactly matches beginning of the autofilled value. I.e. autofilled value "+1 (555) 123-4567" will work with "+1" or "+1 (5", but won't work with "+1 (\_\_\_) \_\_\_-\_\_\_\_" or "1 (555)". There are several possible solutions:

1. Set `maskChar` to null and trim space after "+1" with `beforeMaskedStateChange` if no more digits are entered.
2. Apply mask only if value is not empty. In general, this is the most reliable solution because we can't be sure about formatting in autofilled value.
3. Use less formatting in the mask.

Please note that it might lead to worse user experience (should I enter +1 if input is empty?). You should choose what's more important to your users — smooth typing experience or autofill. Phone and ZIP code inputs are very likely to be autofilled and it's a good idea to care about it, while security confirmation code in two-factor authorization shouldn't care about autofill at all.