# Masked Input

> Source: https://design.nanatec.co.ke/components/masked-input/
> A text field shaped by a pattern, such as a date, a KRA PIN or a number plate, that writes in the separators as people type.

The masked input takes a value with a fixed shape: a date, a KRA PIN, a number plate, an
account number. People type only the characters; the field accepts the right kind in each
place and writes in the separators. For a phone number use the
[phone input](/components/phone-input/), which knows each country's length and dialling
code; for a number someone adjusts, the [number input](/components/number-input/).

## Preview

## Installation

```html
<nana-masked-input label="KRA PIN" mask="A#########A" uppercase name="pin"></nana-masked-input>

<script type="module">
  const pin = document.querySelector('nana-masked-input');
  pin.addEventListener('nana-change', (event) => {
    console.log(event.detail.value, event.detail.complete);
  });
</script>
```

The element takes part in its form: it submits `value` under `name`, resets with the
form, and is disabled with a disabled fieldset. `nana-input` fires while typing and
`nana-change` when the field is left.

## Masks

| Character | Takes |
| --- | --- |
| `#` | A digit |
| `A` | A letter |
| `*` | A letter or a digit |
| `\` | Makes the next character a literal, so `\#` is a `#` |
| Anything else | Written in for the person |

Some masks:

| Value | Mask |
| --- | --- |
| Date | `##/##/####` |
| KRA PIN | `A#########A` |
| Number plate | `AAA ###A` |
| Card expiry | `##/##` |
| Account number | `#### #### ####` |

A separator appears once the character after it is typed, so Backspace removes characters
rather than stopping at a slash. A separator someone types or pastes is accepted, so
`12/05/2026` and `12052026` give the same value. Characters that do not fit their place are
skipped, and typing stops when the mask is full. Set `uppercase` to upper-case letters.

## The value

The value holds only the characters typed: `12052026`. Set `keepLiterals` (`keep-literals`
on the element) to hold and submit it as shown instead: `12/05/2026`. A value you set can
be written either way.

## Validation

A value that does not fill the mask blocks the form, and once the field is left it shows
"Complete this field". With `required`, an empty field blocks the form too. For any other
problem, such as a date in the future, set `invalid` with your own `errorMessage`.

Use `placeholder` to show the shape before anything is typed, such as `DD/MM/YYYY`.

## Accessibility

- The field asks for the number pad (`inputmode="numeric"`) when every place takes a
  digit, and the keyboard otherwise.
- Autocomplete and spellcheck are off, since browsers rarely hold these values and would
  mark a PIN as misspelt.
- Say what goes in the field in its label or help, such as "As on your ID"; the mask alone
  does not tell anyone the expected order of day and month.
- The help text describes the field; an error replaces it and is announced.

## API
