Format As You Type

The simplest field formatting and masking tool for React.

Format fields the way you want using the input components you already use. Real-time. No hassle.

Overview

• Install by running npm i format-as-you-type or yarn add format-as-you-type.
• Import to a React component using import useFieldFormatter from 'format-as-you-type'.
• Define a hook instance by passing in:
  1. A formatter (see below),
  2. A callback function that executes onChange (E.g., const birthdayFormatter = useFieldFormatter(formatDate, setBirthday);), and
  3. (Optionally) a custom ref prop to use on your field instead of the default ref={}.†
• The hook instance contains props to pass to your input component. Implement them by simply adding { ...yourConstantName } at the end of the component’s props.

Want to see more examples? Keep reading!

† As you will see further below, there are some custom input components that won’t behave as expected when using ref={}.

Generic Formatters

While you can make your own formatters, there are a few that are ready to use:

• formatDate
• formatPhone
• formatCreditCard
• formatBigNumber
• formatPostalCodeCanada

More generic formatters will be added with upcoming versions. However, if you have an idea for a new one, feel free to suggest it by creating an issue.

See the API header further below to learn more about each function’s options and parameters.

Make Your Own Formatter

Generic formatters not getting the job done? Make your own! Just import formatString. Here’s an example:

import { formatString } from 'format-as-you-type';

const formatCustom = (newInput, options, /* any additional parameters */) => {
  // Any extra logic goes here...

  return formatString(newInput, '0000 / 0000 \ 0000', options);
};

Custom formats can either contain placeholder characters such as A for letters and 0 for numbers (e.g. (000) 000-0000), or actual letters and numbers (e.g. (604) 123-4567). All that matters is where separators (non-numbers and non-letters) are placed.

***** The only rule is that the first parameter must be the string being formatted and the second parameter must accept an options argument. *****

Implementing a Formatter in a Plain HTML Field

Implementing useFieldFormatter in a plan HTML field is easy:

import React from 'react';
import useFieldFormatter, { formatDate } from 'format-as-you-type';

const YourFormComponent = (props) => {
  const [birthday, setBirthday] = React.useState('');

  const birthdayFormatter = useFieldFormatter(formatDate, setBirthday);

  return (
    <form>
      /* ... */

      <label htmlFor="birthday">Birthday</label>
      <input
        id="birthday"
        value={birthday}
        { ...birthdayFormatter }
      />

      /* ... */
    </form>
  );
};

Implementing a Formatter in a Custom Component

When using useFieldFormatter on a custom text field component, you may encounter warnings, errors, or other unpredictable behaviour. That’s because, in the context of our example, spreading birthdayFormatter in a component yields the following by default:

<InputComponent
  /* other props */
  onChange={(event) => ourChangeHandler(event)}
  ref={ourInternalInputRef}
/>

Some custom input components don’t work without using a different prop instead, such as innerRef, inputRef, etc., or wrapping the component in a React.forwardRef.

Since we can’t (yet) predict what type of component the hook will be spread into, the simplest solution, at the moment, is to provide the ref prop as the third argument when initializing useFieldFormatter.

In Material-UI’s case, this is inputRef. If you use another library and run into problems, give their documentation a read. For our example, though, we’ll stick to Material-UI:

import React from 'react';
import useFieldFormatter, { formatDate } from 'format-as-you-type';
import TextField from '@mui/material/TextField';

const YourFormComponent = (props) => {
  const [birthday, setBirthday] = React.useState('');

  const birthdayFormatter = useFieldFormatter(formatDate, setBirthday, 'inputRef');

  return (
    <form>
      /* ... */

      <TextField
        label="Birthday"
        value={birthday}
        { ...birthdayFormatter }
      />

      /* ... */
    </form>
  );
};

API

useFieldFormatter

useFieldFormatter(formatter, onChange, refProp = 'ref')

Parameters

formatDate

formatDate(newInput, options, format = 'YYYY-MM-DD')

formatPhone

formatPhone(newInput, options, format = '(000) 000-0000')

formatCreditCard

formatCreditCard(newInput, options, infoType = 'NUMBER')

Special parameters

Info

• This formatter is intended for credit cards with 16-digit numbers.
• If the first digit of a credit card’s number is 3, it will be formatted like an AMEX card. Otherwise, it’ll be formatted in groups of four digits.
• If your form might take credit cards with more than 16 numbers, feel free to make a custom formatter using formatString (see further below).

formatBigNumber

formatBigNumber(newInput, options, locale)

Special parameters

† This list will be converted to type LocaleTypes = ... once this package is converted to TypeScript very soon.

formatPostalCodeCanada

formatBigNumber(newInput, options)

Info

This function simply formats strings to match the A0A 0A0 format.

formatString

formatString(newInput, format, options)

Special parameters

Options

GitHub

View Github