input-format

Formatting user's text input on-the-fly

See Demo

GitHub Ban

On March 9th, 2020, GitHub, Inc. silently banned my account (and all my libraries) without any notice for an unknown reason. I opened a support ticked but they didn't answer. Because of that, I had to move all my libraries to GitLab.

Install

npm install input-format --save

Concept

input-format operates on two representations of the same "value":

• A "parsed" value
• A "formatted" value

An example could be a phone number:

• A "parsed" phone number is "2133734253"
• A "formatted" phone number is "(213) 373-4253"

When a user inputs any text into the input field, that text gets "parsed" in order to get the "parsed" value. After that, the "parsed" value is "formatted" again in order to force the input field text to adhere to that specific format.

For example, consider a user that inputs "213-373-42-53" into the input field. That text gets "parsed" into value: "2133734253". One could notice that while the "parsed" value is correct, the input text itself has incorrect "format", which should be fixed. So the value gets "formatted" using the proper format, and the resulting string "(213) 373-4253" is set as the input field value. This is how "parse" and "format" functions work together and are two sides of the same coin.

Usage

Start by defining parse() and format() functions:

• parse() will be called for each character in the input string and its job is to "parse" each such individual character, i.e. to filter out any "punctuation". After "parsing" each individual character, input-format will concatenate those parsed characters into a combined "parsed" string and will set the value to that string.
  • For example, when "parsing" a phone number input text "(213) 373-4253", the parse() function would filter out any non-digit characters — return isDigit(char) ? char : "" — resulting in a combined "parsed" string "2133734253".
• format() function transforms the "parsed" value back into a "formatted" string. It should return an object of shape: { value: string, template: string }, where value: string is a "formatted" string and template: string is the template that was used for "formatting".
  • For example, when "formatting" a phone number, the format() function would transform a "parsed" value "2133734253" into a "formatted" value "(213) 373-4253".

The ability to provide custom parse() and format() functions provides a degree of flexibility for this input component. However, the most common use case would still be "masked input" where the input value must adhere to a certain pre-defined "template". To support this common case, the package exports two utility functions that create parse() and format() functions from just a custom template string:

• templateParser(template, parseCharacter) creates a parse() function for a given template string.
  • Arguments:
    • template: string — A template string with "x" character used as a placeholder. Example: "(xxx) xxx-xxxx".
    • parseCharacter: (string) => string — Parses a single input character. Basically, this is the parse() function itself, in which case one could ask: "What's the point of calling templateParser() to get the parse() function when the parse() function is already known?". The answer would be: "The parse() function returned from templateParser() function has a correct maximum character limit that is derived from the template string".
      • For example, in case of a phone number input, the parseCharacter() function should only leave the digits and ignore any "punctuation", so it could look like return isDigit(char) ? char : "".
• templateFormatter(template) creates a format() function for a given template string.

An example of getting parse() and format() functions for a US phone number input:

import { templateParser, templateFormatter, parseDigit } from 'input-format'

// US phone number template
const TEMPLATE = '(xxx) xxx-xxxx'

// `parse` function parses input text characters one-by-one.
//
// `function parse(character, value, context) { return character }`
//
// Arguments:
//  * `character` is the currently parsed input text character.
//  * `value` is the parsed value so far.
//  * `context` is just a utility empty object that is shared within the bounds
//    of parsing a single input string. The `parse()` function could
//    use that object to store any kind of "flags" in it in order to alter
//    its behavior based when parsing next characters within the same string.
//    Or it could completely ignore it.
//
// Returns:
//  * If it returns anything (not `undefined`) then it is appended to the `value`
//
// `parseDigit` is an exported helper `parse` function
// that returns `character` if it's a digit
// (a common case, e.g. phone numbers input).
//
// `templateParser` wrapper is a small helper
// which enhances `parse` function to limit `value` max length
// to the number of "x"-es in the template.
//
const parse = templateParser(TEMPLATE, parseDigit)

// `format` function formats parsed value.
//
// function format(value) { return { text: '(800) 555-3535', template: '(xxx) xxx-xxxx' } }
//
// Arguments:
//  * `value` is the parsed value to be formatted.
//
// Returns `{ text, template }`, where:
//  * `text` is the formatted text
//  * `template` is the template used to format the `text`
//    (can be a partial template or a full template)
//
// If the `value` couldn't be formatted then
// `format()` should just return `undefined`.
//
// `templateFormatter` helper creates a formatter based on a template.
//
const format = templateFormatter(TEMPLATE)

Having parse() and format() functions, one could use them to render the actual input component.

React Hook

import { useInput } from 'input-format/react-hook'

const [phone, setPhone] = useState('2133734253')

// Returns "controlled" `<input/>` `props`.
const inputProps = useInput({
  value: phone,
  onChange: setPhone,
  parse: templateParser("(xxx) xxx-xxxx", parseDigit),
  format: templateFormatter("(xxx) xxx-xxxx")
})

// Outputs "(213) 373-4253"
<input type="tel" {...inputProps}/>

useInput() hook parameters:

• ref — An optional ref. Supports both setRef(element) functions and useRef() objects.
• value: string? — "Parsed" value. Can be undefined or null.
• onChange(value: string?) — Will be called when a new value is "parsed". Also note that it should be a function of value rather than a function of event.
• parse() — A parse() function.
• format() — A format() function.

useInput() hook returns <input/> props:

• ref — Specifically, a setRef(element) function.
• value: string
• onChange(event: Event)
• onKeyDown(event: Event)

By default, useInput() hook works in "controlled" mode. It could be changed to "uncontrolled" mode, if required. In that case, pass slightly different parameters to the hook:

• value: string? — Don't pass this parameter.
• defaultValue: string? — (optional) Pass this parameter to specify the initial value.
• controlled: boolean? — Pass false as the value for this parameter.

The <input/> props returned from useInput() hook in "uncontrolled" mode will also be slightly different:

• value: string — This property won't be present.
• defaultValue: string — This property will be present.

React

The React component is simply a wrapper around useInput() hook described above.

import ReactInput from 'input-format/react'

const [phone, setPhone] = useState('2133734253')

// Renders a "controlled" `<input/>.
<ReactInput
  value={phone}
  onChange={setPhone}
  parse={templateParser("(xxx) xxx-xxxx", parseDigit)}
  format={templateFormatter("(xxx) xxx-xxxx")}
/>

// Outputs "(213) 373-4253"
{phone}

P.S. Note that the onChange() property of the <ReactInput/> component should be a function of value, not a function of event.

DOM

import {
  onChange,
  onKeyDown
} from 'input-format'

// `parse()` and `format()` functions should be defined.
const parse = ...
const format = ...

// Get the `<input/>` element.
const input = document.querySelector('input')

// Get notified when the `<input/>` value changes.
const onChangeListener = (value) => {
  console.log('Value has changed:', value)
}

// Add "onchange" listener to the `<input/>` element.
input.addEventListener('change', (event) => {
  onChange(event, input, parse, format, onChangeListener)
})

// Add "onkeydown" listener to the `<input/>` element.
input.addEventListener('keydown', (event) => {
  onKeyDown(event, input, parse, format, onChangeListener)
})

Low-level API

This is an example of using "low-level API" — the exported parse() and format() functions themselves — by calling them directly rather than passing them to one of the package's "high-level API" (DOM or React). For example, this "low-level API" could be used to create a new "high-level API" for some new DOM framework, or to implement an input component for a non-DOM environment.

import { parse, format } from 'input-format'

// Input character parser for `parse()`.
//
// `context` argument is just a utility empty object that is shared within the bounds
// of parsing a single input string. The `_parse()` function could use that object
// to store any kind of "flags" in it in order to alter its behavior based when
// parsing next characters within the same string. Or it could completely ignore it.
//
function _parse(character, value, context) {
  if (value.length < 10) {
    if (character >= '0' && character <= '9') {
      return character
    }
  }
}

// Output text formatter for `format()`.
function _format(value) {
  ...
  // Just as an example of a return value
  return {
    text: '(800) 555-3535',
    template: '(xxx) xxx-xxxx'
  }
}

// Testing.

let value
let text = '(800) 555-3535'
let caret = 4 // before the first zero

// `parse()`.

{ value, caret } = parse(text, caret, _parse)

value === '8005553535'
caret === 2

// `format()`.

{ text, caret } = format(value, caret, _format)

value === '(800) 555-3535'
caret === 4

Contributing

After cloning this repo, ensure dependencies are installed by running:

npm install

This module is written in ES6 and uses Babel for ES5 transpilation. Widely consumable JavaScript can be produced by running:

npm run build

Once npm run build has run, you may import or require() directly from node.

After developing, the full test suite can be evaluated by running:

npm test

When you're ready to test your new functionality on a real project, you can run

npm pack

It will build, test and then create a .tgz archive which you can then install in your project folder

npm install [module name with version].tar.gz

License

MIT