README.md

React Input Mask

React Input Mask is an open source library for React that provides an easy way to apply masks to input fields.

Masks can be used to enforce specific formatting for user input, such as phone numbers, social security numbers, and credit card numbers. With React Input Mask, you can define a mask for your input field, and the library will automatically format the user's input according to the specified mask.

Why React Input Mask?

React Input Mask is a lightweight library that provides a simple API for applying masks to input fields. It is built on top of React Hooks, and is designed to be used with functional components. It is also compatible with libraries such as react-hook-form. The design philosophy behind React Input Mask is to provide a simple API that is easy to use and understand via a hook instead of a component.

It is also designed to be used with Next.js and Remix.run and other server-side rendering frameworks.

Installation

React Input Mask can be installed via npm or yarn:

npm install @code-forge/react-input-mask

yarn add @code-forge/react-input-mask

Usage

Using React Input Mask is easy. Simply import the useInputMask hook from the library, and pass the mask prop to the hook. The hook will return an object containing the value and onMouseDown props that you can pass to your input field.

import React from 'react';
import { useInputMask } from '@code-forge/react-input-mask';

const MyComponent = () => {
  const { getInputProps } = useInputMask({ mask: 'One does not simply walk into AAAAAA' });
  return (
    <input name="phone" {...getInputProps()} onChange={e => {
      // Your onChange handler gets the output of the hook (won't trigger if the input is invalid)
      console.log(e.target.value);
    }} />
  );
};

In the example above, we've applied a mask to fill the word needed to complete the sentence.

You can customize the mask to fit your needs by using a variety of special characters that represent different types of input.

Character	Description
9	Represents a number.
A	Represents a letter.
*	Represents a wildcard.

Available Props

Prop	Type	Description	Default
mask	string	The mask to apply to the input field.	undefined
placeholderChar	string	The character to use as a placeholder for the mask characters (eg. 999-999 with placeholderChar set to "@" will produce @@@-@@@).	"_"
charRegex	RegExp	A regular expression that represents the characters that are allowed to be entered into the input field.	/^[a-zA-Z]*$/
numRegex	RegExp	A regular expression that represents the numbers that are allowed to be entered into the input field.	/^[0-9]*$/
type	"raw" or "mask"	The type of value to return from the hook. If set to "raw", the hook will return the raw value of the input field (eg. mask 999-999-99 with 111-111-11 will output 11111111). If set to "mask", the hook will return the masked value of the input field. (eg. mask 999-999-99 with 111-111-11 will output 111-111-11)	"raw"
value	string	The initial value of the input field. (The hook expects to be given a value created by itself, if you provide an invalid value it will try to fill as much of the mask as it can but relies on you to pass it a positive value, otherwise it will default to its default values)	undefined

Examples

Phone Number

import React from 'react';
import { useInputMask } from '@code-forge/react-input-mask';

const MyComponent = () => {
  const { getInputProps } = useInputMask({ mask: '+(999) 999-9999' });
  return (
    <input name="phone" {...getInputProps()} />
  );
};

Social Security Number

import React from 'react';
import { useInputMask } from '@code-forge/react-input-mask';

const MyComponent = () => {
  const { getInputProps } = useInputMask({ mask: '999-99-9999' });
  return (
    <input name="ssn" {...getInputProps()} />
  );
};

Credit Card Number

import React from 'react';
import { useInputMask } from '@code-forge/react-input-mask';

const MyComponent = () => {
  const { getInputProps } = useInputMask({ mask: '9999 9999 9999 9999' });
  return (
    <input name="cc" {...getInputProps()} />
  );
};

Handle keyDown before the mask

import React from 'react';
import { useInputMask } from '@code-forge/react-input-mask';

const MyComponent = () => {
  const { getInputProps } = useInputMask({ mask: '9999 9999 9999 9999' });
  const maskProps = getInputProps();
  return (
    <input name="cc" onKeyDown={e => { 
      // do something
      maskProps.onKeyDown(e);
    }} value={maskProps.value} />
  );
};

Usage with react-hook-form

import React from 'react';
import { useForm } from 'react-hook-form';
import { useInputMask } from '@code-forge/react-input-mask';

const MyComponent = () => {
  const { register, handleSubmit } = useForm();
  const { getInputProps } = useInputMask({ mask: '9999 9999 9999 9999' });
  return (
    <form onSubmit={handleSubmit(data => console.log(data))}>
      <input {...register('cc')} {...getInputProps()} />
      <button type="submit">Submit</button>
    </form>
  );
};

Support

If you like the project, please consider supporting us by giving a ⭐️ on Github.

License

MIT

Bugs

If you find a bug, please file an issue on our issue tracker on GitHub

Contributing

Thank you for considering contributing to @code-forge/react-input-mask! We welcome any contributions, big or small, including bug reports, feature requests, documentation improvements, or code changes.

To get started, please fork this repository and make your changes in a new branch. Once you're ready to submit your changes, please open a pull request with a clear description of your changes and any related issues or pull requests.

Please note that all contributions are subject to our Code of Conduct. By participating, you are expected to uphold this code.

We appreciate your time and effort in contributing to react-input-mask and helping to make it a better tool for the community!