# Input mask

> Formats a text field's value to a pattern, such as a phone or card number, as people type, paste or compose.

## Anatomy

Add `data-mask` to a [text field](/text-inputs.html.md) so what people type takes a pattern, such as a phone or card number.

The mask goes on an `<input>` of type `text`, `tel`, `search`, `url` or `password`, the types with a caret. `AutoInit()` starts every one. Show the expected format in the supporting text, and add `inputmode="numeric"` to a digit-only mask so phones open a number pad.

 Phone Format: (555) 123-4567

 Card number 16 digits

 Postal code Format: K1A 0B1

```
<div class="field">
  <input id="phone" name="phone" type="tel" inputmode="numeric" autocomplete="tel-national"
         placeholder=" " data-mask="(000) 000-0000" aria-describedby="phone_help">
  <label for="phone">Phone</label>
  <small id="phone_help">Format: (555) 123-4567</small>
</div>
```

## Mask syntax

In the mask, `0` takes a digit, `a` takes a letter and `*` takes either. Every other character is a literal the mask writes itself. A backslash makes the next character a literal, so `\0` writes a zero and `\a` writes an a.

## Typing, pasting and deleting

Each character that fits fills the next slot, and the mask writes the literals that come before it: typing `5551` into `(000) 000-0000` shows `(555) 1`. A character that fits no slot is dropped, as is one past the end. A paste or autofill keeps the characters that fit and skips the rest, so `555.123.4567` becomes `(555) 123-4567`. The caret stays after the last character the edit added.

A typed character matches only the literal that comes next, so in a `+1 (000) 000-0000` mask a typed leading 1 fills the first slot. A paste or autofill that starts with `+1` matches the prefix. Leave a country code out of the mask, or say in the supporting text not to type it. A mask with no slot leaves the field alone.

Backspace right after a literal, or Delete right before one, removes the digit across it, and the digits after it move back. [Keypad](/keypad.html.md) keys format like typing; with the caret right after a literal, its Backspace moves the caret before the literal, and a second press deletes the digit. After a formatted edit, undo does not step back, because setting the value clears the field's undo history.

## The submitted value

The form submits the value as the field shows it, and `pattern`, `required` and the length checks run on that value. A saved value is formatted when the component starts, without an `input` or `change` event, and again after a form reset. The component formats before the page's own `input` listeners run, so they read the formatted value. A value a script sets is formatted once the script fires an `input` event. In a right-to-left page, add `dir="ltr"` to a phone or card number field.

## IME composition

While an input method editor composes, the field keeps what it writes and formats once the composition ends. Full-width digits count as digits. Android keyboards can treat ordinary typing as composition, so a letter mask there may format only when a word ends; a number pad does not compose.

## Methods

```
const mask = Expressive.InputMask.getInstance(document.getElementById('phone'));
mask.destroy(); // removes the listeners and leaves the value as it is
```