# 🛠️ @energma/input-mask-react
Input Mask React
`input-mask-react` is a React component for creating input fields with customizable input masks. It allows you to format user input according to a specified mask, handling dynamic cursor positions and formatting on-the-fly. This component supports various types of input masks such as numbers, letters, and both formats.
## Compatibility
- **React 19+**
- **NEXT 15+**
## Table of Contents
- [Features](#features)
- [Installation](#installation)
- [Summary](#summary)
- [Compatibility](#compatibility)
- [Schema Types](#schema-types)
- [Usage](#usage)
- [Props](#props)
- [Examples](#examples)
- [Credit Card Expiration Date](#credit-card-expiration-date)
- [Zip Code](#zip-code)
- [Canadian Zip Code](#canadian-zip-code)
- [Telephone Number](#telephone-number)
- [Credit Card Number](#credit-card-number)
- [Country Code](#country-code)
- [License](#license)
## Features
- **Customizable Mask**: You can define a mask format using a symbol (e.g., `_`) that will be replaced with user input.
- **Dynamic Cursor Management**: The cursor position updates automatically as the user types, ensuring that the mask format is followed properly.
- **Type-based Input Sanitization**: The input is sanitized based on the selected type (numbers, letters, or mixed).
- **React Integration**: It is built specifically for use with React, and works seamlessly with TypeScript.
## Installation
To install the `@energma/input-mask-react` package, run the following command in your project:
```bash
npm install @energma/input-mask-react
```
```bash
pnpm add @energma/input-mask-react
```
```bash
yarn add @energma/input-mask-react
```
## Summary
This repository contains code for input-react-mask
(https://github.com/Energma/input-mask-react)
## Schema Types:
- **numbers type accept [0-9]**
- **letters type accept [a-zA-Z]**
- **mixed type accept [a-zA-Z0-9]**
- schema symbol can be of any character
#### Schema interface:
```jsx
interface Schema {
mask: string;
symbol: string;
type: "numbers" | "letters" | "mixed";
}
```
## Usage
### Masked Input Example in React (TypeScript)
This example demonstrates how to use `@energma/input-mask-react` in a React application with TypeScript.
```tsx
import { MaskedInput, Schema } from "@energma/input-mask-react";
import { useState } from "react";
function MyComponent() {
const [creditCardExpiration, setCreditCardExpiration] = useState("");
const schema: Schema = {
mask: "__/__",
symbol: "_",
type: "numbers",
};
return (
setCreditCardExpiration(e.target.value)}
placeholder={schema.mask}
/>
);
}
```
### Masked Input Example in Next.js
In Next.js use `"use client"` directive to ensure that component is treated as a client component.
This example demonstrates how to use `@energma/input-mask-react` in a Next.js client component.
```tsx
"use client";
import { useState } from "react";
import { MaskedInput, Schema } from "@energma/input-mask-react";
export default function MyComponent() {
const [creditCardExpiration, setCreditCardExpiration] = useState("");
const schema: Schema = {
mask: "__/__",
symbol: "_",
type: "numbers",
};
return (
setCreditCardExpiration(e.target.value)}
placeholder={schema.mask}
/>
);
}
```
You can also add object where properties can be `className`, `id`, `label`, etc like any other `input element`.
`placeholder` can be anything you like but good practice is to have mask there.
## Props
| Prop | Type | Description |
| ----------------- | ------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **...InputProps** | | Inherit all [props of `Input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input). |
| **`schema`** | [schema](#schema-types) | Object defines the masking rules for user input.
- `mask` (string) – Defines the input pattern using a placeholder symbol. If it is a `RegExp`, it will validate the input.
- `symbol` (string) – Represents the character that will be replaced by user input.
- `type` (string) – Specifies the [type](#schema-types) of input allowed.
**REQUIRED** |
| **`value`** | number | The value for controlled input.
**REQUIRED** |
| **`onChange`** | function | Callback that is called when the input's text changes.
**REQUIRED** |
| **`onFocus`** | function | Triggered when the user clicks away and then focuses again. It will position the cursor at the next valid input. |
# Examples
### Credit Card Expiration Date
```jsx
setCreditCardExpiration(e.target.value)}
placeholder="__/__"
/>
```
### Zip Code
```jsx
setZipCode(e.target.value)}
placeholder="_____"
/>
```
### Canadian Zip Code
```jsx
setCanadianZipCode(e.target.value)}
placeholder="XXX XXX"
/>
```
### Telephone Number
```jsx
setTelephone(e.target.value)}
placeholder="(XXX)XXX-XXXX"
/>
```
### Credit Card Number
```jsx
setCreditCardNumber(e.target.value)}
placeholder="0000 0000 0000 0000"
/>
```
### Country Code
```jsx
setCountryCode(e.target.value)}
placeholder="XXX"
/>
```
These examples demonstrate the flexibility of the `MaskedInput` component and how it can be integrated into a React application to handle various input formats.
## License
`@energma/input-mask-react` is released under the MIT license. See [LICENSE](./LICENSE) for details.