# As-you-type input

> Format CNIC, mobile number and IBAN fields while the user types, and tell a half-typed value apart from a wrong one.

Source: https://pakdatakit.dev/docs/input/

`import { formatCNICInput, checkCNICInput, formatPhoneInput, checkPhoneInput, formatIBANInput, checkIBANInput } from 'pakdatakit/input'`

Format a field while the user types, and tell a half-typed value apart from a wrong one, so you don't show an error before they've finished. Each formatter returns the value to show in the input; each checker returns an `InputState`: `'empty'`, `'incomplete'`, `'valid'` or `'invalid'`.

Mark the field invalid only for `'invalid'`. An `'incomplete'` value can still become valid, so it is not an error yet. In React, for example:

```tsx
const [cnic, setCnic] = useState('');
const state = checkCNICInput(cnic);

<input
  value={cnic}
  onChange={(e) => setCnic(formatCNICInput(e.target.value))}
  aria-invalid={state === 'invalid'}
/>;
```

For ready-made inputs in React, Vue, Angular and Flutter, and for schema validation, see [Forms](https://pakdatakit.dev/docs/forms/).

## Examples

**TypeScript**

```ts
import { formatCNICInput, checkCNICInput, formatPhoneInput, checkIBANInput } from 'pakdatakit';

formatCNICInput('3520212345');
// → '35202-12345'

checkCNICInput('35202-12');
// → 'incomplete'

formatPhoneInput('+923001234567');
// → '+92 300 1234567'

checkIBANInput('GB29');
// → 'invalid'
```

**Python**

```python
from pakdatakit import format_cnic_input, check_cnic_input, format_phone_input, check_iban_input

format_cnic_input('3520212345')
# → '35202-12345'

check_cnic_input('35202-12')
# → 'incomplete'

format_phone_input('+923001234567')
# → '+92 300 1234567'

check_iban_input('GB29')
# → 'invalid'
```

**Dart**

```dart
import 'package:pakdatakit/pakdatakit.dart';

formatCNICInput('3520212345');
// → '35202-12345'

checkCNICInput('35202-12');
// → InputState.incomplete

formatPhoneInput('+923001234567');
// → '+92 300 1234567'

checkIBANInput('GB29');
// → InputState.invalid
```

**C#**

```csharp
using PakDataKit;

Input.FormatCnic("3520212345");
// → "35202-12345"

Input.CheckCnic("35202-12");
// → InputState.Incomplete

Input.FormatPhone("+923001234567");
// → "+92 300 1234567"

Input.CheckIban("GB29");
// → InputState.Invalid
```

**PHP**

```php
use PakDataKit\Input;

Input::formatCnic('3520212345');
// → '35202-12345'

Input::checkCnic('35202-12');
// → 'incomplete'

Input::formatPhone('+923001234567');
// → '+92 300 1234567'

Input::checkIban('GB29');
// → 'invalid'
```

## Reference

### InputState

```ts
type InputState = 'empty' | 'incomplete' | 'valid' | 'invalid';
```

- `empty`: nothing entered yet
- `incomplete`: what has been typed so far can still become valid
- `valid`: complete and valid
- `invalid`: cannot become valid by typing more (wrong character, prefix or length)

### formatCNICInput()

```ts
function formatCNICInput(value: string): string;
```

**Parameters.** `value`: the current input value.

**Returns** the value to show in the input, grouped as `35202-1234567-1` as the groups fill.

**Caveats.** Keeps up to 13 digits; Urdu digits are converted and other characters are dropped.

**Related:** [`checkCNICInput()`](#checkcnicinput), [CNIC](https://pakdatakit.dev/docs/cnic/).

### checkCNICInput()

```ts
function checkCNICInput(value: string): InputState;
```

**Parameters.** `value`: the current input value, formatted or not.

**Returns** an [`InputState`](#inputstate). A value that cannot start a CNIC, such as `05202` (no province starts with 0), is `'invalid'` straight away.

**Caveats.** A complete value is `'valid'` when [`validateCNIC()`](https://pakdatakit.dev/docs/cnic/#validatecnic) accepts it, so the same limits apply: it is a format check, not identity verification.

**Related:** [`formatCNICInput()`](#formatcnicinput), the [CNIC checker](https://pakdatakit.dev/tools/cnic/).

### formatPhoneInput()

```ts
function formatPhoneInput(value: string): string;
```

**Parameters.** `value`: the current input value.

**Returns** the value to show in the input: `0300-1234567`, or `+92 300 1234567` when the user starts with the country code.

**Related:** [`checkPhoneInput()`](#checkphoneinput), [Phone](https://pakdatakit.dev/docs/phone/).

### checkPhoneInput()

```ts
function checkPhoneInput(value: string): InputState;
```

**Parameters.** `value`: the current input value, formatted or not.

**Returns** an [`InputState`](#inputstate) for a Pakistani mobile number.

**Caveats.** The `03XX` prefix is checked as soon as it is complete, so an unallocated prefix such as `0360` is `'invalid'` before the rest is typed.

**Related:** [`formatPhoneInput()`](#formatphoneinput), [`validatePhone()`](https://pakdatakit.dev/docs/phone/).

### formatIBANInput()

```ts
function formatIBANInput(value: string): string;
```

**Parameters.** `value`: the current input value.

**Returns** the value to show in the input: uppercase, in groups of four (`PK36 SCBL 0000 0011 2345 6702`), up to 24 characters.

**Related:** [`checkIBANInput()`](#checkibaninput), [IBAN](https://pakdatakit.dev/docs/iban/).

### checkIBANInput()

```ts
function checkIBANInput(value: string): InputState;
```

**Parameters.** `value`: the current input value, formatted or not.

**Returns** an [`InputState`](#inputstate) for a Pakistani IBAN. A value that does not start with `PK`, such as `GB29`, is `'invalid'`.

**Caveats.** The `PK` prefix, check digits and bank code are checked as they are typed; the full checksum only once all 24 characters are in.

**Related:** [`formatIBANInput()`](#formatibaninput), the [IBAN checker](https://pakdatakit.dev/tools/iban/).

## Related

- [Forms](https://pakdatakit.dev/docs/forms/): ready-made inputs for React, Vue, Angular and Flutter, and schema validation adapters.
- [API reference for `pakdatakit/input`](https://pakdatakit.dev/api/typescript/input/).
