🛠️ @energma/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
• Installation
• Summary
• Compatibility
• Schema Types
• Usage
• Props
• Examples
  • Credit Card Expiration Date
  • Zip Code
  • Canadian Zip Code
  • Telephone Number
  • Credit Card Number
  • Country Code
• 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:

npm install @energma/input-mask-react

pnpm add @energma/input-mask-react

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:

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.

import { MaskedInput, Schema } from "@energma/input-mask-react";
import { useState } from "react";

function MyComponent() {
  const [creditCardExpiration, setCreditCardExpiration] = useState<string>("");

  const schema: Schema = {
    mask: "__/__",
    symbol: "_",
    type: "numbers",
  };

  return (
    <MaskedInput
      schema={schema}
      value={creditCardExpiration}
      onChange={(e) => 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.

"use client";

import { useState } from "react";
import { MaskedInput, Schema } from "@energma/input-mask-react";

export default function MyComponent() {
  const [creditCardExpiration, setCreditCardExpiration] = useState<string>("");

  const schema: Schema = {
    mask: "__/__",
    symbol: "_",
    type: "numbers",
  };

  return (
    <MaskedInput
      schema={schema}
      value={creditCardExpiration}
      onChange={(e) => 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. | | schema | schema         | 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 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

<MaskedInput
  schema={{ mask: "__/__", symbol: "_", type: "numbers" }}
  value={creditCardExpiration}
  onChange={(e) => setCreditCardExpiration(e.target.value)}
  placeholder="__/__"
/>

Zip Code

<MaskedInput
  schema={{ mask: "_____", symbol: "_", type: "numbers" }}
  value={zipCode}
  onChange={(e) => setZipCode(e.target.value)}
  placeholder="_____"
/>

Canadian Zip Code

<MaskedInput
  schema={{ mask: "XXX XXX", symbol: "X", type: "mixed" }}
  value={canadianZipCode}
  onChange={(e) => setCanadianZipCode(e.target.value)}
  placeholder="XXX XXX"
/>

Telephone Number

<MaskedInput
  schema={{ mask: "(XXX)XXX-XXXX", symbol: "X", type: "numbers" }}
  value={telephone}
  onChange={(e) => setTelephone(e.target.value)}
  placeholder="(XXX)XXX-XXXX"
/>

Credit Card Number

<MaskedInput
  schema={{ mask: "0000 0000 0000 0000", symbol: "0", type: "numbers" }}
  value={creditCardNumber}
  onChange={(e) => setCreditCardNumber(e.target.value)}
  placeholder="0000 0000 0000 0000"
/>

Country Code

<MaskedInput
  schema={{ mask: "XXX", symbol: "X", type: "letters" }}
  value={countryCode}
  onChange={(e) => 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 for details.