React Confirmation Code Input

React hook and component for integrating a confirmation code input into your application
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

1. About The Project
2. Getting Started
   • Prerequisites
   • Installation
3. Usage
4. License
5. Contact

About The Project

This library provides a hook that lets you write a confirmation code input component while the library manages the refs and some interactions like focusing the next input element when an input has been entered. It can thus be considered headless.

The library also provides you with a component implemented on top of that hook. It lets you override the input and container elements' styling by passing respective class names of your choice as properties to the component.

(back to top)

Getting Started

Prerequisites

This is a react library primarily providing a headles react hook for you to implement your own confirmation code input whilst delegating the handling of the element refs and some of the behaviour to said hook. You therefore need a react version as a peer dependency that has support for hooks i.e. any version of react >= 16.8.

Installation

NPM

npm install react-confirmation-code-input

Yarn

yarn add react-confirmation-code-input

PNPM

pnpm add react-confirmation-code-input

(back to top)

Usage

Usage utilizing the hook

import * as React from "react";
import { useConfirmationCodeInput } from "react-confirmation-code-input";
import "./style.css";

export default function App() {
  const {
    refs,
    value: inputs,
    clear,
    setFocus,
    reset,
    inputProps,
  } = useConfirmationCodeInput({
    length: 5,
    allowedPattern: "numeric",
    initialValue: "01234",
    autoFocus: true,
  });

  // reset and setFocus take optional params so we can't pass them directly
  // to onClick but have to eliminate the optional parameter first
  const onReset = React.useCallback(() => reset(), []);
  const onSetFocus = React.useCallback(() => setFocus(), []);

  return (
    <main>
      <div className="input-container">
        {refs.map((ref, index) => (
          <input key={index} value={inputs[index]} ref={ref} {...inputProps} />
        ))}
      </div>
      <div className="button-box">
        <button onClick={onReset}>Reset</button>
        <button onClick={clear}>Clear</button>
        <button onClick={onSetFocus}>Focus</button>
      </div>
    </main>
  );
}

Using the provided Component

import * as React from "react";
import {
  ConfirmationCodeInput,
  ConfirmationCodeInputHandles as Handles,
} from "react-confirmation-code-input";
import "./style.css";

export default function App() {
  const handlesRef = React.useRef<Handles>(null);
  const { reset, clear, setFocus } = React.useMemo(
    () => ({
      reset: () => handlesRef.current.reset(),
      clear: () => handlesRef.current.clear(),
      setFocus: () => handlesRef.current.setFocus(),
    }),
    []
  );

  return (
    <main>
      <ConfirmationCodeInput
        ref={handlesRef}
        length={5}
        allowedPattern="numeric"
        autoFocus
        initialValue="01234"
      />
      <div className="button-box">
        <button onClick={reset}>Reset</button>
        <button onClick={clear}>Clear</button>
        <button onClick={setFocus}>Focus</button>
      </div>
    </main>
  );
}

(back to top)

API

hook version

The hook takes an object as parameter and returns an object as a result:

useConfirmationCodeInput(options: UseConfirmationCodeInputProps) => UseConfirmationCodeInputResult

UseConfirmationCodeInputProps:

allowedPattern?: AllowedPattern;
autoFocus?: boolean;
useValueHook?: UseValue;
initialValue?: string;
length: number;
onChange?: (value: string) => void;

Parameter	Description	Type	Required	Default
allowedPattern	Accepted pattern	AllowedPattern	no	"numeric"
useValueHook	The hook to store and modify the input value	UseValue	no
autoFocus	wheter to put focus on first input upon mounting	boolean	no	true
initialValue	Initial value as string	string	no
length	Number of individual inputs	number	yes
onChange	method called when the value changes	(value: string) => void	no

AllowedPattern:

Allowed Pattern is either one of the predefined patterns "numeric" | "alpha" | "alphanumeric", a RegExp or a function with the following signature:

(input: string, index: number, value: string[]) => boolean;

UseValue

Only provide this if you want to intercept/modify the input or the way it is stored. The signature is as follows:

(options: UseValueOptions) => [string[], Mutators];

UseValueOptions and Mutators are described below. You need to provide the same signature if you want to pass in a custom useValue parameter.

UseValueOptions:

An object of the shape { allowedPattern: AllowedPattern, length: number }:

Property	Description
allowedPattern	The pattern for valid inputs
length	The length of a valid code

Mutators:

An object of the shape:

{
    clear: () => void;
    reset: (value?: string) => void;
    update: (input: string, index: number, options: UpdateOptions) => void;
}

Property	Description	Type
clear	A method to clear the value	() => void
reset	A method to reset the value to either the given value	(value?: string) => void
update	A method to update the value upon a given input character	(input: string, index: number, options: UpdateOptions) => void

UseConfirmationCodeInputResult:

The result of calling useConfirmationCodeInput is an option adhering to the following interface:

    refs: Array<RefObject<HTMLInputElement>>;
    value: string[];
    reset: (value?: string) => void;
    clear: () => void;
    setFocus: (index?: number) => void;
    inputProps: {
        onFocus: FocusEventHandler<HTMLInputElement>;
        onKeyDown: KeyboardEventHandler<HTMLInputElement>;
        onPaste: ClipboardEventHandler<HTMLInputElement>;
        onInput: FormEventHandler<HTMLInputElement>;
    };

Property	Description	Type
refs	An array of refs each of which needs to be passed to the respective input element	Array<RefObject<HTMLInputElement>>
value	The current value as a string array with each value comprising a single character	string[]
reset	see Mutators	(value?: string) => void
clear	see Mutators	() => void
setFocus	see Mutators	(index?: number) => void
inputProps	The object with properties that must be passed to each individual input	InputProps

InputProps

The inputProps returned by the useConfirmationCodeInputResult hook are supposed to be spread into each of the input elements. They comprise needed event handlers on which the hook relies in order to react to user events.

Property	Description	Type
onFocus	onFocus event handler	FocusEventHandler<HTMLInputElement>
onKeyDown	onKeyDown event handler	KeyboardEventHandler<HTMLInputElement>
onPaste	onPaste event handler	ClipboardEventHandler<HTMLInputElement>
onInput	onInput event handler	FormEventHandler<HTMLInputElement>

Component

The component takes the following parameters:

Property	Description	Type	Required	Default
ref	reference to get access to the exposed Mutators	React.MutableRefObject	no
length	See corresponding hook param	number	yes
allowedPattern	See corresponding hook param	AllowedPattern	no	numeric
initialValue	See corresponding hook param	string	no
onChange	See corresponding hook param	(value: string) => void	no
autoFocus	See corresponding hook param	boolean	no
containerCls	CSS class to be appended to the input container's class names	string	no
inputCls	CSS class to be appended to the input's class names	string	no
disabled	Whether the inputs are disabled	boolean	no
isPassword	Whether the inputs are of type password	boolean	no

License

Distributed under the MIT License. See LICENSE for more information.

(back to top)

Contact

Project Link: https://github.com/momesana/react-confirmation-code-input

(back to top)